@voxgig/apidef 5.10.0 → 6.0.0

package/dist/transform/select.js.map

@@ -1 +1 @@
-{"version":3,"file":"select.js","sourceRoot":"","sources":["../../src/transform/select.ts"],"names":[],"mappings":";;;AAEA,uCAA+B;AAK/B,oCAA8B;AAqB9B,MAAM,eAAe,GAAc,KAAK,WACtC,GAAQ;IAER,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,GAAG,CAAA;IACpC,MAAM,GAAG,GAAa,QAAQ,CAAC,IAAI,CAAC,WAAG,CAAC,CAAA;IAExC,IAAI,GAAG,GAAG,SAAS,CAAA;IAEnB,IAAA,eAAI,EAAC,GAAG,CAAC,MAAM,EAAE,CAAC,IAAiB,EAAE,QAAgB,EAAE,EAAE;QACvD,IAAA,eAAI,EAAC,IAAI,CAAC,EAAE,EAAE,CAAC,GAAY,EAAE,OAAe,EAAE,EAAE;YAC9C,IAAA,eAAI,EAAC,GAAG,CAAC,MAAM,EAAE,CAAC,OAAoB,EAAE,EAAE;gBACxC,MAAM,IAAI,GAAY,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;gBAC7C,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,CAAA;YAChD,CAAC,CAAC,CAAA;YACF,IAAI,IAAI,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;gBAChD,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,CAAA;YAC9B,CAAC;QACH,CAAC,CAAC,CAAA;QAEF,GAAG,IAAI,IAAI,CAAC,IAAI,GAAG,GAAG,CAAA;IACxB,CAAC,CAAC,CAAA;IAEF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAA;AAC1B,CAAC,CAAA;AAwEC,0CAAe;AArEjB,SAAS,aAAa,CACpB,KAAY,EACZ,IAAiB,EACjB,IAAa,EACb,OAAoB,EACpB,KAAc;IAEd,MAAM,MAAM,GAAQ,OAAO,CAAC,MAAM,CAAA;IAClC,MAAM,KAAK,GAAQ,OAAO,CAAC,IAAI,CAAA;IAE/B,MAAM,QAAQ,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAA;IAExD,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAY,EAAE,EAAE;QAC5B,IAAA,eAAI,EAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,IAAc,EAAE,EAAE;YACnC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBACtC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YAC9B,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAA;IAEnB,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACpC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAErC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACjB,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAA;QAEnD,IAAI,IAAI,IAAI,OAAO,EAAE,CAAC;YACpB,MAAM,CAAC,OAAO,GAAG,OAAO,CAAA;QAC1B,CAAC;IACH,CAAC;AAEH,CAAC;AAGD,SAAS,UAAU,CACjB,MAAa,EACb,KAAkB,EAClB,GAAY;IAEZ,uEAAuE;IACvE,MAAM,UAAU,GAAG,IAAI,GAAG,EAAuB,CAAA;IACjD,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QAC5B,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;IAChD,CAAC;IAED,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAc,EAAE,CAAc,EAAE,EAAE;QACjD,0BAA0B;QAC1B,IAAI,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAA;QACzD,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC;YAChB,IAAI,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACzD,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;oBAChD,CAAC,CAAC,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;YAC/C,CAAC;YAED,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC;gBAChB,MAAM,WAAW,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAE,CAAA;gBACtC,MAAM,WAAW,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAE,CAAA;gBACtC,KAAK,GAAG,WAAW,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;oBACtC,WAAW,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;YACrC,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAA;IACd,CAAC,CAAC,CAAA;AACJ,CAAC"}
+{"version":3,"file":"select.js","sourceRoot":"","sources":["../../src/transform/select.ts"],"names":[],"mappings":"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"}

package/dist/transform/top.js

@@ -16,17 +16,49 @@ const types_1 = require("../types");
 const topTransform = async function (ctx) {
     const { apimodel, def } = ctx;
     const kit = apimodel.main[types_1.KIT];
-    kit.info = def.info;
-    kit.info.servers = def.servers ?? [];
+    kit.info = stringifyInfoScalars(def.info ?? {});
+    kit.info.servers = stringifyInfoScalars(def.servers ?? []);
     // Swagger 2.0
     if (def.host) {
         kit.info.servers.push({
             url: (def.schemes?.[0] ?? 'https') + '://' + (0, struct_1.join)([def.host, def.basePath], '/', true)
         });
     }
+    // A usable SDK requires a base URL. OpenAPI 3 puts it in `servers[].url`;
+    // Swagger 2 derives it from `host` + `basePath`. If neither yields a
+    // non-empty url, the generated SDK has no way to issue requests, so fail
+    // the apidef model build rather than emit broken code.
+    const firstServerUrl = kit.info.servers?.[0]?.url;
+    if (null == firstServerUrl || '' === String(firstServerUrl).trim()) {
+        throw new Error('apidef: no server URL found in API definition (servers[0].url is required).');
+    }
     return { ok: true, msg: 'top' };
 };
 exports.topTransform = topTransform;
+// OpenAPI's `info` object (and the `servers` array) declares every scalar
+// leaf as a string. YAML/JSON parsers don't enforce that — `version: 2`
+// without quotes parses as the number 2, `version: true` as a boolean.
+// Apidef's downstream schema (apidef.jsonic) unifies info fields as
+// `string`, so non-string scalars cause an aontu unify failure during
+// model resolution. Normalise scalar leaves to strings here, at the
+// model-build boundary, rather than relax the schema.
+function stringifyInfoScalars(node) {
+    if (null == node)
+        return node;
+    if (Array.isArray(node))
+        return node.map(stringifyInfoScalars);
+    if ('object' === typeof node) {
+        const out = {};
+        for (const [k, v] of Object.entries(node)) {
+            out[k] = stringifyInfoScalars(v);
+        }
+        return out;
+    }
+    if ('number' === typeof node || 'boolean' === typeof node) {
+        return String(node);
+    }
+    return node;
+}
 // export type {
 //   GuideEntity,
 // }

package/dist/transform/top.js.map

@@ -1 +1 @@
-{"version":3,"file":"top.js","sourceRoot":"","sources":["../../src/transform/top.ts"],"names":[],"mappings":";;;AACA,2CAAqC;AAErC,oCAA8B;AAmB9B,6BAA6B;AAC7B,yCAAyC;AACzC,8BAA8B;AAC9B,gCAAgC;AAGhC,uBAAuB;AACvB,kBAAkB;AAClB,oCAAoC;AAEpC,uBAAuB;AACvB,iCAAiC;AACjC,IAAI;AAGJ,MAAM,YAAY,GAAG,KAAK,WACxB,GAAQ;IAER,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,GAAG,CAAA;IAC7B,MAAM,GAAG,GAAa,QAAQ,CAAC,IAAI,CAAC,WAAG,CAAC,CAAA;IAExC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAA;IACnB,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAA;IAEpC,cAAc;IACd,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QACb,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;YACpB,GAAG,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,GAAG,KAAK,GAAG,IAAA,aAAI,EAAC,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC;SACvF,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,CAAA;AACjC,CAAC,CAAA;AAIC,oCAAY;AAId,gBAAgB;AAChB,iBAAiB;AACjB,IAAI"}
+{"version":3,"file":"top.js","sourceRoot":"","sources":["../../src/transform/top.ts"],"names":[],"mappings":";;;AACA,2CAAqC;AAErC,oCAA8B;AAmB9B,6BAA6B;AAC7B,yCAAyC;AACzC,8BAA8B;AAC9B,gCAAgC;AAGhC,uBAAuB;AACvB,kBAAkB;AAClB,oCAAoC;AAEpC,uBAAuB;AACvB,iCAAiC;AACjC,IAAI;AAGJ,MAAM,YAAY,GAAG,KAAK,WACxB,GAAQ;IAER,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,GAAG,CAAA;IAC7B,MAAM,GAAG,GAAa,QAAQ,CAAC,IAAI,CAAC,WAAG,CAAC,CAAA;IAExC,GAAG,CAAC,IAAI,GAAG,oBAAoB,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAA;IAC/C,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,oBAAoB,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAA;IAE1D,cAAc;IACd,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QACb,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;YACpB,GAAG,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,GAAG,KAAK,GAAG,IAAA,aAAI,EAAC,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC;SACvF,CAAC,CAAA;IACJ,CAAC;IAED,0EAA0E;IAC1E,qEAAqE;IACrE,yEAAyE;IACzE,uDAAuD;IACvD,MAAM,cAAc,GAAQ,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAA;IACtD,IAAI,IAAI,IAAI,cAAc,IAAI,EAAE,KAAK,MAAM,CAAC,cAAc,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CACb,6EAA6E,CAC9E,CAAA;IACH,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,CAAA;AACjC,CAAC,CAAA;AA4BC,oCAAY;AAzBd,0EAA0E;AAC1E,wEAAwE;AACxE,uEAAuE;AACvE,oEAAoE;AACpE,sEAAsE;AACtE,oEAAoE;AACpE,sDAAsD;AACtD,SAAS,oBAAoB,CAAC,IAAS;IACrC,IAAI,IAAI,IAAI,IAAI;QAAE,OAAO,IAAI,CAAA;IAC7B,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAA;IAC9D,IAAI,QAAQ,KAAK,OAAO,IAAI,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAwB,EAAE,CAAA;QACnC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1C,GAAG,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAAA;QAClC,CAAC;QACD,OAAO,GAAG,CAAA;IACZ,CAAC;IACD,IAAI,QAAQ,KAAK,OAAO,IAAI,IAAI,SAAS,KAAK,OAAO,IAAI,EAAE,CAAC;QAC1D,OAAO,MAAM,CAAC,IAAI,CAAC,CAAA;IACrB,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAQD,gBAAgB;AAChB,iBAAiB;AACjB,IAAI"}

package/dist/types.d.ts

@@ -1002,6 +1002,7 @@ type KitModel = {
 };
 type ApiDefResult = {
     ok: boolean;
+    reload?: boolean;
     start: number;
     end: number;
     steps: string[];
@@ -1102,4 +1103,4 @@ type GuidePathOp = {
 export { KIT, OpenControlShape, OpenModelShape, OpenBuildShape, };
 export type { Guide, GuideMetrics, GuideEntity, GuidePath, GuidePathAction, GuideRenameParam, GuidePathOp, KitModel, MethodName, TypeName, Log, FsUtil, ApiDefOptions, ApiDefResult, Control, Model, Build, ApiModel, ApiDefContext, Warner, Metrics, };
 export type { CmpDesc, BasicMethodDesc, MethodDesc, MethodEntityDesc, EntityDesc, EntityPathDesc, PathDesc, OpDesc, } from './desc';
-export type { OpName, ModelEntityRelations, ModelOpMap, ModelFieldOp, ModelField, ModelArg, ModelTarget, ModelOp, ModelEntity, } from './model';
+export type { OpName, ModelEntityRelations, ModelOpMap, ModelFieldOp, ModelField, ModelArg, ModelPoint, ModelOp, ModelEntity, } from './model';

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA,4CAA4C;;;AAK5C,iCAAwC;AAGxC,MAAM,GAAG,GAAG,KAAK,CAAA;AAyOf,kBAAG;AAzML,MAAM,YAAY,GAAG,IAAA,aAAK,EAAC;IACzB,IAAI,EAAE;QACJ,KAAK,EAAE,IAAI;QACX,KAAK,EAAE,IAAI;QACX,YAAY,EAAE,IAAI;QAClB,QAAQ,EAAE,IAAI;QACd,QAAQ,EAAE,IAAI;KACf;CACF,CAAC,CAAA;AACF,MAAM,gBAAgB,GAAG,IAAA,aAAK,EAAC,IAAA,YAAI,EAAC,YAAY,CAAC,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAA;AAkMrE,4CAAgB;AA5LlB,MAAM,UAAU,GAAG,IAAA,aAAK,EAAC;IACvB,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,MAAM;IACX,IAAI,EAAE;QACJ,CAAC,GAAG,CAAC,EAAE,EAAE;QACT,GAAG,EAAE,EAAE;QACP,GAAG,EAAE;YACH,KAAK,EAAE,EAAE;YACT,MAAM,EAAE,EAAE;SACX;KACF;CACF,CAAC,CAAA;AACF,MAAM,cAAc,GAAG,IAAA,aAAK,EAAC,IAAA,YAAI,EAAC,UAAU,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAA;AAiL/D,wCAAc;AA5KhB,MAAM,UAAU,GAAG,IAAA,aAAK,EAAC;IACvB,IAAI,EAAE;QACJ,IAAI,EAAE,EAAE;QACR,IAAI,EAAE,EAAE;QACR,KAAK,EAAE,EAAE;QACT,GAAG,EAAE,EAAE;QACP,GAAG,EAAE,EAAE;QACP,OAAO,EAAE,EAAE;QACX,GAAG,EAAE,EAAE;QACP,EAAE,EAAE,IAAA,WAAG,GAAE;QACT,MAAM,EAAE,KAAK;QACb,SAAS,EAAE,EAAE;QACb,KAAK,EAAE;YACL,GAAG,EAAE,IAAI;YACT,GAAG,EAAE,IAAI;YACT,GAAG,EAAE,IAAI;SACV;KACF;CACF,CAAC,CAAA;AACF,MAAM,cAAc,GAAG,IAAA,aAAK,EAAC,IAAA,YAAI,EAAC,UAAU,CAAC,CAAC,CAAA;AA0J5C,wCAAc"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA,4CAA4C;;;AAK5C,iCAAwC;AAGxC,MAAM,GAAG,GAAG,KAAK,CAAA;AA6Of,kBAAG;AA7ML,MAAM,YAAY,GAAG,IAAA,aAAK,EAAC;IACzB,IAAI,EAAE;QACJ,KAAK,EAAE,IAAI;QACX,KAAK,EAAE,IAAI;QACX,YAAY,EAAE,IAAI;QAClB,QAAQ,EAAE,IAAI;QACd,QAAQ,EAAE,IAAI;KACf;CACF,CAAC,CAAA;AACF,MAAM,gBAAgB,GAAG,IAAA,aAAK,EAAC,IAAA,YAAI,EAAC,YAAY,CAAC,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAA;AAsMrE,4CAAgB;AAhMlB,MAAM,UAAU,GAAG,IAAA,aAAK,EAAC;IACvB,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,MAAM;IACX,IAAI,EAAE;QACJ,CAAC,GAAG,CAAC,EAAE,EAAE;QACT,GAAG,EAAE,EAAE;QACP,GAAG,EAAE;YACH,KAAK,EAAE,EAAE;YACT,MAAM,EAAE,EAAE;SACX;KACF;CACF,CAAC,CAAA;AACF,MAAM,cAAc,GAAG,IAAA,aAAK,EAAC,IAAA,YAAI,EAAC,UAAU,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAA;AAqL/D,wCAAc;AAhLhB,MAAM,UAAU,GAAG,IAAA,aAAK,EAAC;IACvB,IAAI,EAAE;QACJ,IAAI,EAAE,EAAE;QACR,IAAI,EAAE,EAAE;QACR,KAAK,EAAE,EAAE;QACT,GAAG,EAAE,EAAE;QACP,GAAG,EAAE,EAAE;QACP,OAAO,EAAE,EAAE;QACX,GAAG,EAAE,EAAE;QACP,EAAE,EAAE,IAAA,WAAG,GAAE;QACT,MAAM,EAAE,KAAK;QACb,SAAS,EAAE,EAAE;QACb,KAAK,EAAE;YACL,GAAG,EAAE,IAAI;YACT,GAAG,EAAE,IAAI;YACT,GAAG,EAAE,IAAI;SACV;KACF;CACF,CAAC,CAAA;AACF,MAAM,cAAc,GAAG,IAAA,aAAK,EAAC,IAAA,YAAI,EAAC,UAAU,CAAC,CAAC,CAAA;AA8J5C,wCAAc"}

package/model/apidef.jsonic

@@ -10,8 +10,11 @@ main: kit: entity: &: {
 
   name: key()
   active: *true
-  
-  id: {
+
+  # Present only when the spec models an id for this entity (response /
+  # request schema declares one, or examples imply one). Public APIs that
+  # return payloads without an id leave this undefined.
+  id?: {
     field: string
     name: string
   }
@@ -41,13 +44,46 @@ main: kit: entity: &: {
 
       parts: [ &: string ]
 
+      # Each arg kind (path params, query, header, cookie) has the same
+      # element shape. `kind` is constrained to the kind tag matching the
+      # array it appears in; `example` is optional and captures a spec-
+      # provided example value used by test generators.
       args: {
-        params: [ &: {
+        params?: [ &: {
+          active: *true
+          kind: 'param'
+          name: string
+          orig?: string
+          reqd: boolean
+          type: top
+          example?: top
+        } ]
+        query?: [ &: {
+          active: *true
+          kind: 'query'
+          name: string
+          orig?: string
+          reqd: boolean
+          type: top
+          example?: top
+        } ]
+        header?: [ &: {
+          active: *true
+          kind: 'header'
+          name: string
+          orig?: string
+          reqd: boolean
+          type: top
+          example?: top
+        } ]
+        cookie?: [ &: {
           active: *true
-          kind: string
+          kind: 'cookie'
           name: string
+          orig?: string
           reqd: boolean
           type: top
+          example?: top
         } ]
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/apidef",
-  "version": "5.10.0",
+  "version": "6.0.0",
   "main": "dist/apidef.js",
   "type": "commonjs",
   "types": "dist/apidef.d.ts",
@@ -40,7 +40,7 @@
     "LICENSE"
   ],
   "devDependencies": {
-    "@types/node": "25.6.0",
+    "@types/node": "25.6.2",
     "typescript": "6.0.3"
   },
   "peerDependencies": {

package/src/apidef.ts

@@ -284,8 +284,21 @@ function ApiDef(opts: ApiDefOptions) {
           warn.history.map(n => formatJSONIC(n)).join('\n\n'))
       }
 
+      // apidef writes model source files (entity, flow, guide jsonics) into
+      // .sdk/model/. Downstream actions (sdkgen, etc.) read those via
+      // sdk.jsonic @-includes, so voxgig-model has to re-resolve the model
+      // before the post-step actions run. Signal reload whenever jostraca
+      // wrote or merged any files; if nothing changed on disk,
+      // voxgig-model's resolveModel cache short-circuits the re-read.
+      const jfiles = jres?.files
+      const reload = !!jfiles && (
+        (jfiles.written?.length ?? 0) > 0 ||
+        (jfiles.merged?.length ?? 0) > 0
+      )
+
       return {
         ok: true,
+        reload,
         err: null,
         start,
         end: Date.now(),
@@ -398,17 +411,22 @@ export type {
 
 export type {
   OpName,
+  ArgKind,
+  NamesCluster,
   ModelEntityRelations,
   ModelOpMap,
   ModelFieldOp,
   ModelField,
   ModelArg,
-  ModelTarget,
+  ModelPoint,
   ModelOp,
   ModelEntity,
   Model,
   ModelEntityFlow,
   ModelEntityFlowStep,
+  ModelEntityFlowStepInput,
+  ModelEntityFlowStepValidator,
+  ModelEntityFlowStepSpec,
 } from './model'
 
 

package/src/builder/flow/flowHeuristic01.ts

@@ -17,7 +17,7 @@ import {
 import type {
   ModelEntity,
   ModelOp,
-  ModelTarget,
+  ModelPoint,
 } from '../../model'
 
 import {
@@ -196,7 +196,7 @@ function resolveBasicEntityFlow(ctx: any, entity: any) {
 }
 
 
-function findMainLoadPoint(op: ModelOp): ModelTarget | undefined {
+function findMainLoadPoint(op: ModelOp): ModelPoint | undefined {
   let cands = op.points.filter(a => '{id}' === getelem(a.parts, -1))
   return cands[0]
 }

package/src/model.ts

@@ -9,18 +9,41 @@ import type { MethodName } from './types'
 type OpName = 'load' | 'list' | 'create' | 'update' | 'remove' | 'patch' | 'head' | 'options'
 
 
-type Model = {
+// Argument kinds supported on operation points.
+type ArgKind = 'param' | 'query' | 'header' | 'cookie'
+
+
+// jostraca's `names()` helper sticks several stylised forms of the project
+// name onto an object: `name`, `Name`, `NAME`, plus snake/dash variants.
+// Templates that reach for any of these expect the cluster to be present.
+type NamesCluster = {
   name: string
+  Name: string
+  NAME: string
+}
+
+
+// Top-level unified API model produced by apidef + voxgig-model. Templates
+// access the kit through `model.main.kit.<thing>`. The `info`, `config`,
+// `feature`, and `target` kits remain `any` for now because their shapes are
+// less stable than entity/flow — Phase 2 of the refactor types them.
+type Model = NamesCluster & {
   origin?: string
+  def?: string
 
-  const: {
-    // TODO: remove
-    Name: string
+  const: NamesCluster & {
+    year?: number
   }
 
   main: {
     kit: {
+      info: any
+      config: any
       entity: Record<string, ModelEntity>
+      feature: Record<string, any>
+      flow: Record<string, ModelEntityFlow>
+      target: Record<string, any>
+      option?: Record<string, any>
     }
   }
 }
@@ -52,18 +75,27 @@ type ModelField = {
 }
 
 
-// Operation argument/parameter definition
+// Operation argument/parameter definition.
+// `example` captures a value the spec advertises (parameter `example`,
+// the first entry of `examples`, or `schema.example`/`schema.default`).
+// Test generators use this for required params in live test setup so the
+// generated request actually satisfies the API contract.
 type ModelArg = {
   name: string
   orig: string
   type: any // @voxgig/struct validation schema
-  kind: 'param' | 'query' | 'header' | 'cookie'
+  kind: ArgKind
   reqd: boolean
+  example?: any
 }
 
 
-// Point implementation of an operation
-type ModelTarget = {
+// One concrete HTTP endpoint that can satisfy an operation. An entity op
+// (load/list/create/...) carries an array of these — apidef chooses
+// between them at runtime via `select.exist` matching against reqmatch /
+// reqdata. (Originally named `ModelTarget`; renamed for consistency with
+// the field name `points` and the runtime utility `MakePoint`.)
+type ModelPoint = {
   orig: string
   method: MethodName
   parts: string[]
@@ -93,19 +125,31 @@ type ModelTarget = {
 // Operation definition
 type ModelOp = {
   name: OpName
-  points: ModelTarget[]
+  points: ModelPoint[]
 }
 
 
-// Entity definition - core model entity with operations and fields
+// Entity definition - core model entity with operations and fields.
+// `id` is present only when the OpenAPI response/request schema declares
+// (or examples imply) an `id` field on the entity. Public APIs that return
+// payloads without an id (e.g. read-only feeds) leave it undefined.
+//
+// `Name`, `NAME` etc. are stamped on by jostraca's `names()` helper after
+// apidef hands the model to the generator. They're typed as optional here
+// so apidef's transform code can construct entities without them; template
+// code should reach for them through `nom(entity, 'Name')` rather than
+// direct property access, which both works pre-`names()` and lets us
+// remove the optional later.
 type ModelEntity = {
-  name: string,
-  op: ModelOpMap,
-  fields: ModelField[],
-  id: {
-    name: string,
-    field: string,
-  },
+  name: string
+  Name?: string
+  NAME?: string
+  op: ModelOpMap
+  fields: ModelField[]
+  id?: {
+    name: string
+    field: string
+  }
   relations: ModelEntityRelations
 }
 
@@ -116,36 +160,69 @@ type ModelEntityFlow = {
   kind: string
   // args: Record<string, string>
   step: ModelEntityFlowStep[]
+  active?: boolean
+}
+
+
+// Per-step input cluster. Test-generators name the variables they emit by
+// reading these slots, falling back to derived defaults. All fields are
+// optional — `newFlowStep` in transform/flowstep.ts guarantees the input
+// object itself exists, so consumers don't need to null-check `step.input`.
+type ModelEntityFlowStepInput = {
+  ref?: string
+  entvar?: string
+  matchvar?: string
+  datavar?: string
+  listvar?: string
+  resdatavar?: string
+  markdefvar?: string
+  srcdatavar?: string
+  suffix?: string
+  textfield?: string
+  id?: any
+  [extra: string]: any
+}
+
+
+// Validators and specs are user-supplied callables identified by the
+// `apply` discriminator; `def` is the validator-specific options bag.
+type ModelEntityFlowStepValidator = {
+  apply: string
+  def: Record<string, any>
+}
+
+type ModelEntityFlowStepSpec = {
+  apply: string
+  def: Record<string, any>
 }
 
 
 type ModelEntityFlowStep = {
   op: OpName
-  input: Record<string, any>
+  input: ModelEntityFlowStepInput
   match: Record<string, any>
   data: Record<string, any>
-  spec: {
-    apply: string
-    def: Record<string, any>
-  }[]
-  valid: {
-    apply: string
-    def: Record<string, any>
-  }[]
+  spec: ModelEntityFlowStepSpec[]
+  valid: ModelEntityFlowStepValidator[]
 }
 
 
 export type {
   OpName,
+  ArgKind,
+  NamesCluster,
   Model,
   ModelEntityRelations,
   ModelOpMap,
   ModelFieldOp,
   ModelField,
   ModelArg,
-  ModelTarget,
+  ModelPoint,
   ModelOp,
   ModelEntity,
   ModelEntityFlow,
   ModelEntityFlowStep,
+  ModelEntityFlowStepInput,
+  ModelEntityFlowStepValidator,
+  ModelEntityFlowStepSpec,
 }

package/src/transform/args.ts

@@ -21,7 +21,7 @@ import type {
   OpName,
   ModelOp,
   ModelEntity,
-  ModelTarget,
+  ModelPoint,
   ModelArg,
 } from '../model'
 
@@ -38,16 +38,16 @@ const argsTransform: Transform = async function(
 
   each(kit.entity, (ment: ModelEntity, entname: string) => {
     each(ment.op, (mop: ModelOp, opname: OpName) => {
-      each(mop.points, (mtarget: ModelTarget) => {
+      each(mop.points, (mpoint: ModelPoint) => {
         const argdefs: ParameterDef[] = []
 
-        const pathdef: PathDef = def.paths[mtarget.orig]
+        const pathdef: PathDef = def.paths[mpoint.orig]
         argdefs.push(...(pathdef.parameters ?? []))
 
-        const opdef: MethodDef = (pathdef as any)[mtarget.method.toLowerCase()]
+        const opdef: MethodDef = (pathdef as any)[mpoint.method.toLowerCase()]
         argdefs.push(...(opdef?.parameters ?? []))
 
-        resolveArgs(ment, mop, mtarget, argdefs)
+        resolveArgs(ment, mop, mpoint, argdefs)
       })
 
     })
@@ -67,7 +67,7 @@ const ARG_KIND: Record<string, ModelArg["kind"]> = {
 }
 
 
-function resolveArgs(ment: ModelEntity, mop: ModelOp, mtarget: ModelTarget, argdefs: ParameterDef[]) {
+function resolveArgs(ment: ModelEntity, mop: ModelOp, mpoint: ModelPoint, argdefs: ParameterDef[]) {
   const touchedKeys = new Set<string>()
 
   each(argdefs, (argdef: ParameterDef) => {
@@ -79,7 +79,7 @@ function resolveArgs(ment: ModelEntity, mop: ModelOp, mtarget: ModelTarget, argd
     // Rename map can be keyed by either the spec original (camelCase) or by
     // the snakified form depending on which path went through heuristic01.
     // Try both before falling through to `orig`.
-    const renameMap = mtarget.rename[kind]
+    const renameMap = mpoint.rename[kind]
     const name = renameMap?.[specName] ?? renameMap?.[orig] ?? orig
     const marg: ModelArg = {
       name,
@@ -89,12 +89,17 @@ function resolveArgs(ment: ModelEntity, mop: ModelOp, mtarget: ModelTarget, argd
       reqd: !!argdef.required
     }
 
+    const example = resolveArgExample(argdef)
+    if (undefined !== example) {
+      marg.example = example
+    }
+
     if (argdef.nullable) {
       marg.type = ['`$ONE`', '`$NULL`', marg.type]
     }
 
-    const argsKey = (marg.kind === 'param' ? 'params' : marg.kind) as keyof typeof mtarget.args
-    let kindargs = (mtarget.args[argsKey] = mtarget.args[argsKey] ?? [])
+    const argsKey = (marg.kind === 'param' ? 'params' : marg.kind) as keyof typeof mpoint.args
+    let kindargs = (mpoint.args[argsKey] = mpoint.args[argsKey] ?? [])
     kindargs.push(marg)
     touchedKeys.add(argsKey)
   })
@@ -102,11 +107,39 @@ function resolveArgs(ment: ModelEntity, mop: ModelOp, mtarget: ModelTarget, argd
   // Sort once after all args are collected
   const cmp = (a: ModelArg, b: ModelArg) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0
   for (const key of touchedKeys) {
-    mtarget.args[key as keyof typeof mtarget.args]?.sort(cmp)
+    mpoint.args[key as keyof typeof mpoint.args]?.sort(cmp)
   }
 }
 
 
+// OpenAPI lets specs advertise example values four ways:
+//   parameter.example          (single value, OAS 3.0+)
+//   parameter.examples          (named-example object, take first .value)
+//   parameter.schema.example   (single value on the schema)
+//   parameter.schema.default   (default value)
+// Pick the first one we find so test generators can produce valid live
+// requests even when the parameter is required and has no other source.
+function resolveArgExample(argdef: any): any {
+  if (undefined !== argdef?.example) return argdef.example
+
+  const examples = argdef?.examples
+  if (examples && 'object' === typeof examples) {
+    for (const v of Object.values(examples)) {
+      if (v && 'object' === typeof v && undefined !== (v as any).value) {
+        return (v as any).value
+      }
+    }
+  }
+
+  const schema = argdef?.schema
+  if (schema) {
+    if (undefined !== schema.example) return schema.example
+    if (undefined !== schema.default) return schema.default
+  }
+
+  return undefined
+}
+
 
 export {
   argsTransform,