@voxgig/sdkgen 4.21.0 → 4.23.0

package/project/.sdk/src/cmp/cpp/PrepareAuth_cpp.ts

@@ -16,52 +16,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
-// rather than templated. This is the cpp peer of PrepareAuth_ts,
-// PrepareAuth_c and PrepareAuth_go; read PrepareAuth_ts first, it carries
-// the full account of the defect.
-//
-// apidef has always resolved the scheme's `in` and `name` into
-// `main.kit.info.security` — joplin's says `in: "query", name: "token"` —
-// and generation dropped both, hardcoding
-//
-//   static const std::string HEADER_AUTH = "authorization";
-//
-// so the SDK sent a header the API does not read and never sent the query
-// parameter it does.
-//
-// A template cannot fix this, because the three placements need three
-// different bodies and a template has to pick one. A component emits the
-// branch this API actually uses and nothing else — no dead query code in a
-// bearer-token SDK, and no runtime `if` on a value fixed at generation
-// time. In cpp it also keeps the includes honest: the base64 encoder the
-// Basic branch needs (the cpp core ships none) is emitted only by the one
-// placement that can use it.
-//
-// CPP IS THE ONE TARGET WITH NO prepare_auth TEMPLATE TO DELETE. The logic
-// was EMBEDDED in `tm/cpp/utility/pipeline.hpp`, between preparePath and
-// transformRequest, and the extraction shape is the PREFERRED one rather
-// than the whole-module fallback:
-//
-//   - the SDK runtime is HEADER-ONLY, so "its own compilation unit" is its
-//     own HEADER — `utility/prepare_auth.hpp`. Nothing has to move to a
-//     .cpp, nothing new has to be compiled or linked, and the Makefile's
-//     `SDK_HDRS := $(wildcard ... utility/*.hpp ...)` already lists it as a
-//     rebuild dependency of every test binary.
-//
-//   - the BINDING is untouched. `prepareAuth` stays `inline SpecPtr
-//     prepareAuth(CtxPtr)` in `namespace sdk::util`; pipeline.hpp includes
-//     this header at the top (beside `../core/types.hpp`, outside any
-//     namespace) and its `register_all` still binds
-//     `u.prepareAuth = util::prepareAuth;`. Every call site therefore
-//     resolves exactly as before: `utility->prepareAuth(ctx)` in
-//     pipeline.hpp's own makeSpec, `u->prepareAuth(ctx)` in
-//     core/types.hpp, and `utility->prepareAuth(ctx)` in the shipped
-//     test/pipeline_test.cpp and test/primary_utility_test.cpp.
-//
-// Generating the whole of pipeline.hpp instead would have turned 1300 lines
-// of hand-maintained runtime — every other pipeline step, makeOptions, the
-// feature hooks — into a generator string literal to buy one function.
 const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const { target } = props
   const { model } = props.ctx$
@@ -72,20 +26,6 @@ const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const prefix = resolveAuthPrefix(model)
   const basic = isHttpBasicAuth(model)
 
-  // FOLDER NESTING. Main_cpp calls this at ROOT level — after the
-  // `Folder({name:'core'})` that wraps Config and client.hpp has closed —
-  // so `utility` is opened HERE and the file lands at
-  // `<root>/utility/prepare_auth.hpp`, the sibling of the
-  // `utility/pipeline.hpp` that `Copy({from:'tm/cpp'})` brings in and that
-  // `#include "prepare_auth.hpp"`s it by that relative name.
-  //
-  // The call site matters as much as the folder. Putting this beside Config
-  // would write `core/utility/prepare_auth.hpp`: pipeline.hpp's include
-  // would not resolve and the build would fail — loudly, which is the good
-  // case. The bad case is the ts port's: opening a redundant second folder
-  // (`src` there, `utility` here — `utility/utility/prepare_auth.hpp`)
-  // emits a file nothing includes while a stale copy keeps being compiled,
-  // and no test can see it.
   Folder({ name: 'utility' }, () => {
     File({ name: 'prepare_auth.' + target.ext }, () => {
       Content(render({ active, where, name, prefix, basic }))
@@ -94,31 +34,6 @@ const PrepareAuth = cmp(async function PrepareAuth(props: any) {
 })
 
 
-// NOT `isAuthActive`, AND THE DIFFERENCE IS LOAD-BEARING (the py port found
-// this first; six of the twelve ports found it independently).
-//
-// `isAuthActive` is false whenever the SPEC declares no security scheme
-// (`main.kit.info.auth: false`). That is a statement about the DEFINITION,
-// not a ban on ever sending a credential: apidef writes it for every spec
-// with no securitySchemes block, and those SDKs are still expected to
-// honour an `apikey` the caller passes. `optspec` always declares `apikey`,
-// makeOptions fills `options.auth` from the optspec defaults, so the
-// template's `is_nullish(getp(options, "auth"))` guard never actually fired
-// and every such SDK has always sent `options.apikey`.
-//
-// Gating the body on `isAuthActive` therefore does not trim dead code, it
-// deletes working authentication — and takes the secrets feature with it,
-// since that resolves a secret into `options.apikey` and prepareAuth then
-// places nothing. This target has a lane that catches it: generatedcompile's
-// `cpp: auth null beats an explicit apikey` builds test/authnull_probe.cpp
-// against a fixture whose model says `main: kit: info: { ... auth: false }`
-// and requires the baseline `{apikey: 'OPTKEY01'}` to reach
-// `spec->headers["authorization"]`.
-//
-// So the no-op is emitted only when the PROJECT says so:
-// `main.kit.config.auth.active: false`, an explicit per-SDK switch nobody
-// sets by accident. A spec that is merely silent keeps the credential path
-// it has always had.
 function authSwitchedOn(model: any): boolean {
   const auth = getModelPath(model, `main.${KIT}.config.auth`,
     { only_active: false, required: false })
@@ -222,10 +137,6 @@ inline std::string authBase64(const std::string& in) {
 
 `
 
-  // The template's body, unchanged except for WHICH bag the credential
-  // lands in and under what name. Same option keys (`auth`, `apikey`,
-  // `auth.prefix`), same NOT_FOUND sentinel, same `skip` test, same
-  // `throw ctx->makeError("auth_no_spec", ...)`, same Group A reads.
   const preamble = `inline SpecPtr prepareAuth(CtxPtr ctx) {
   SpecPtr spec = ctx->spec;
   if (!spec) throw ctx->makeError("auth_no_spec", "Expected context spec property to be defined.");
@@ -298,15 +209,6 @@ ${place(spec.where)}
 }
 
 
-// COOKIE SPLICING. A cookie IS a header, so the credential rides the header
-// bag — but the `cookie` header is SHARED with whatever cookies the caller
-// set, so our pair is spliced in and out rather than the header assigned
-// over. Splicing also makes this idempotent: a retried request cannot end
-// up carrying the credential twice.
-//
-// `cred` is a parameter rather than a file-scope constant so the one
-// constant in this file stays where the template put it — a function-local
-// static inside prepareAuth.
 function cookieHelpers(): string {
   return `// The cookie header minus our own pair, every other cookie untouched.
 inline std::string authCookieRest(const Value& headers, const std::string& cred) {
@@ -361,35 +263,16 @@ inline void authCookieApply(const Value& headers, const std::string& cred,
 }
 
 
-// The credential's key, as it goes into the bag.
-//
-// A HEADER name is LOWERCASED. HTTP header names are case-insensitive
-// (RFC 9110 5.1), and this SDK's own header map is keyed in lowercase
-// throughout — `content-type` in makeSpec, the `authorization` the shipped
-// test/pipeline_test.cpp and test/primary_utility_test.cpp assert on, the
-// `authorization` feature/secrets.hpp injects and retracts, and the
-// `authorization` generatedcompile's cpp auth-null probe reads — while the
-// template this replaces said `"authorization"` outright. apidef writes
-// `name: "Authorization"`, so emitting the resolver's value verbatim would
-// put the credential under a key nothing in this runtime reads.
-//
-// A QUERY parameter and a COOKIE name are case-SENSITIVE, so those go in
-// verbatim: `?token=` is not `?Token=`.
 function credLiteral(where: string, name: string): string {
   return 'header' === where ? String(name).toLowerCase() : String(name)
 }
 
 
-// The bag the credential lands in, per placement. It is both the local
-// variable name and the Spec field, which in cpp are spelled the same
-// (spec->headers / spec->query). Cookies ride the header bag because a
-// cookie IS a header.
 function bagName(where: string): string {
   return 'query' === where ? 'query' : 'headers'
 }
 
 
-// Drop any stale credential.
 function clear(where: string, indent: number): string {
   const pad = ' '.repeat(indent)
 
@@ -403,22 +286,14 @@ function clear(where: string, indent: number): string {
 
 function place(where: string): string {
   if ('query' === where) {
-    // NO PREFIX IN A QUERY STRING. `?token=Bearer%20abc` is not a thing any
-    // API reads; the prefix is a header convention and is dropped here
-    // deliberately rather than silently concatenated. makeUrl appends
-    // spec->query to the URL after this runs, so the parameter reaches the
-    // wire escaped by the same escurl every other query parameter uses.
     return `    map_put(query, CRED_NAME, Value(apikey.is_string() ? apikey.as_string() : ""));`
   }
 
   if ('cookie' === where) {
-    // NO PREFIX IN A COOKIE either — a cookie carries a bare `name=value`
-    // pair, not a header's scheme-prefixed credential.
     return `    authCookieApply(headers, CRED_NAME,
       apikey.is_string() ? apikey.as_string() : "", false);`
   }
 
-  // The template's header body, unchanged.
   return `    std::string authPrefix = as_str(Struct::getpath(options, {"auth", "prefix"}));
     std::string apikeyVal = apikey.is_string() ? apikey.as_string() : "";
     // A raw credential (empty prefix, e.g. an apiKey scheme) must go in

package/project/.sdk/src/cmp/cpp/ReadmeEntity_cpp.ts

@@ -54,7 +54,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
-    const fields = entity.fields || []
+    const fields = Object.values(entity.fields || {})
     // Model-driven id key: null when this entity has no id-like field.
     const idF = entityIdField(entity)
     // The client accessor is the entity's snake_case name (client->planet()).
@@ -102,8 +102,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
 
       each(fields, (field: any) => {
-        const desc = field.short || ''
-        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
+        const desc = field.sh || ''
+        Content(`| \`${field.n}\` | \`${canonToType(field.t, target.name)}\` | ${desc} |
 `)
       })
 

package/project/.sdk/src/cmp/cpp/ReadmeExamplesTest_cpp.ts

@@ -2,25 +2,6 @@
 import { cmp, Content, File } from '@voxgig/sdkgen'
 
 
-// Emits test/readme_examples_test.cpp — a structural gate over every ```cpp
-// fenced block in the docs that ship C++ examples:
-//   - the root README.md          (top-level, multi-language quick start)
-//   - the per-language cpp/README.md
-//   - the per-language cpp/REFERENCE.md
-//
-// DESIGN NOTE (mirrors ReadmeExamplesTest_c): the go gate shells out to
-// `go build`/`go run` to COMPILE and RUN every block. A faithful C++ port
-// would extract each snippet, wrap it in a translation unit, and drive the
-// bundled Makefile / c++ against the header-only runtime — a large,
-// environment-sensitive harness that cannot be authored safely here. This gate
-// instead validates that every documented C++ block is PRESENT and
-// STRUCTURALLY well-formed (balanced ()[]{}, non-empty). It is a real,
-// always-passing test that keeps the docs honest about block structure;
-// upgrading it to a true compile gate is left as a follow-up. Missing docs are
-// tolerated (a run may generate a subset of phases).
-//
-// The test binary runs with the C++ project root as its working directory, so
-// the doc paths resolve as "README.md", "REFERENCE.md", and "../README.md".
 const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
   const { model } = props.ctx$
 

package/project/.sdk/src/cmp/cpp/ReadmeModel_cpp.ts

@@ -121,13 +121,13 @@ On error, \`ok\` is \`false\` and \`err\` contains the error value.
 
 `)
   each(entityList, (ent: any) => {
-    const fields = ent.fields || []
+    const fields = Object.values(ent.fields || {})
     const opnames = Object.keys(ent.op || {})
     const ops = ent.op || {}
     const points = each(ops).map((op: any) =>
       op.points ? each(op.points) : []
     ).flat()
-    const path = points.length > 0 ? (points[0] as any).orig || '' : ''
+    const path = points.length > 0 ? (points[0] as any).o || '' : ''
 
     Content(`#### ${ent.Name}
 
@@ -135,7 +135,7 @@ On error, \`ok\` is \`false\` and \`err\` contains the error value.
 | --- | --- |
 `)
     each(fields, (field: any) => {
-      Content(`| \`${field.name}\` | ${field.short || ''} |
+      Content(`| \`${field.n}\` | ${field.sh || ''} |
 `)
     })
 

package/project/.sdk/src/cmp/cpp/ReadmeQuick_cpp.ts

@@ -67,7 +67,6 @@ ${ctor}
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
     const article = /^[aeiou]/i.test(eName) ? 'an' : 'a'
-    // The client accessor is the entity's snake_case name (client->planet()).
     const acc = cppVarName(exampleEntity.name)
     const eVar = acc
     const opnames = entityOps(exampleEntity)
@@ -135,8 +134,6 @@ try {
 `)
     }
     else if (opnames.includes('load')) {
-      // Every REQUIRED load-match key (id first, then parent path params like
-      // page_id) — the same shape the runtime resolves path params from.
       const loadRequired = opRequestShape(exampleEntity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>
@@ -163,8 +160,6 @@ try {
 `)
     }
 
-    // Model-driven example fields: derive the create/update body from the op
-    // shape (opRequestShape) so the docs reference REAL writable fields.
     const examplePairs = (opname: string): string[] => {
       const items = opRequestShape(exampleEntity, opname).items
         .filter((it: any) => (it.name !== idF && it.name !== 'id') ||
@@ -208,8 +203,6 @@ client->${acc}()->update(vmap({${updatePairs.join(', ')}}), Value::undef());
 `)
       }
       if (opnames.includes('remove')) {
-        // Every REQUIRED remove-match key: the id (off the created record
-        // when possible) plus parent keys like page_id.
         const removePairs = opRequestShape(exampleEntity, 'remove').items
           .filter((it: any) => !it.optional || it.name === idF)
           .sort((a: any, b: any) =>

package/project/.sdk/src/cmp/cpp/ReadmeRef_cpp.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -57,7 +57,7 @@ const ReadmeRef = cmp(function ReadmeRef(props: any) {
   const { model } = props.ctx$
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  const feature = targetFeatures(model, target)
 
   const publishedEntities = each(entity).filter((e: any) => e.active !== false)
 
@@ -169,7 +169,7 @@ Prepare a fetch definition without sending. Returns the \`fetchdef\` and throws
     // Entity reference sections
     publishedEntities.map((ent: any) => {
       const opnames = Object.keys(ent.op || {})
-      const fields = ent.fields || []
+      const fields = Object.values(ent.fields || {})
       // Model-driven id key: null when this entity has no id-like field.
       const idF = entityIdField(ent)
       const acc = cppVarName(ent.name)
@@ -202,9 +202,9 @@ auto ${acc} = client->${acc}();
 | --- | --- | --- | --- |
 `)
         each(fields, (field: any) => {
-          const req = field.req ? 'Yes' : 'No'
-          const desc = field.short || ''
-          Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${req} | ${desc} |
+          const req = field.r ? 'Yes' : 'No'
+          const desc = field.sh || ''
+          Content(`| \`${field.n}\` | \`${canonToType(field.t, target.name)}\` | ${req} | ${desc} |
 `)
         })
 
@@ -229,7 +229,7 @@ auto ${acc} = client->${acc}();
               if (fop.active === false) return '-'
               return 'Yes'
             })
-            Content(`| \`${field.name}\` | ${cols.join(' | ')} |
+            Content(`| \`${field.n}\` | ${cols.join(' | ')} |
 `)
           })
 
@@ -375,9 +375,6 @@ auto client = std::make_shared<${model.const.Name}SDK>(vmap({
 \`\`\`
 
 `)
-      // The shared feature reference: options, defaults, usage and the
-      // considerations. Model facts, identical in every target, so they are
-      // written once in cmp/ReadmeRefFeatures.ts rather than here.
       ReadmeRefFeatures({ target })
     }
 

package/project/.sdk/src/cmp/cpp/Schema_cpp.ts

@@ -17,27 +17,6 @@ import {
 } from './utility_cpp'
 
 
-// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
-//
-// The cpp peer of src/cmp/ts/Schema_ts.ts. Same two members, same source:
-// optspec from `main.kit.optspec` plus each feature's own `config.options`,
-// entityspec from the entity field sentinels — both built by the shared
-// helpers, so what cpp validates against and what ts validates against cannot
-// drift.
-//
-// EMBEDDED AS JSON, PARSED AT LOAD, where ts emits an object literal: JSON is
-// a subset of TypeScript's own literal syntax and is not a subset of cpp's.
-// Chunked adjacent string literals, exactly as config.hpp carries its config,
-// so no single literal approaches an implementation's minimum-supported
-// length however large the model grows.
-//
-// This REPLACES the OPTSPEC_JSON() that used to sit in pipeline.hpp — a
-// hand-maintained copy of the spec that nothing cross-checked, and which had
-// already drifted (no `extend`, no `server`, no `auth.basic`).
-//
-// The round-trip is exact because the spec holds only strings and booleans:
-// pinned by "strings and booleans only, so the JSON round-trip is lossless"
-// in ts/test/optspec.test.ts.
 const Schema = cmp(async function Schema(props: any) {
   const ctx$ = props.ctx$
   const target = props.target
@@ -54,7 +33,7 @@ const Schema = cmp(async function Schema(props: any) {
     Content(`// ${model.const.Name} SDK: generated schemas. Do not edit.
 //
 // Built from the model: \`main.kit.optspec\` and each feature's
-// \`config.options\` for the option spec; entity \`fields[].type\` for the
+// \`config.options\` for the option spec; entity \`fields{}.type\` for the
 // entity specs.
 
 #ifndef SDK_CORE_SCHEMA_HPP

package/project/.sdk/src/cmp/cpp/TestDirect_cpp.ts

@@ -28,20 +28,20 @@ function normalizePathParams(
       const snaked = snakify(rawName)
       const depluralized = depluralize(snaked)
       const param = params.find((p: any) =>
-          p.name === snaked || p.name === depluralized) ||
+          p.n === snaked || p.n === depluralized) ||
         params.find((p: any) =>
-          p.orig === snaked || p.orig === depluralized)
-      if (param) return '{' + param.name + '}'
+          p.or === snaked || p.or === depluralized)
+      if (param) return '{' + param.n + '}'
       if (rename) {
         for (const [origCamel, renamedTo] of Object.entries(rename)) {
           if (renamedTo === rawName) {
             const origSnaked = snakify(origCamel)
             const origDepluralized = depluralize(origSnaked)
             const renamedParam = params.find(
-              (p: any) => p.orig === origSnaked || p.name === origSnaked ||
-                p.orig === origDepluralized || p.name === origDepluralized
+              (p: any) => p.or === origSnaked || p.n === origSnaked ||
+                p.or === origDepluralized || p.n === origDepluralized
             )
-            if (renamedParam) return '{' + renamedParam.name + '}'
+            if (renamedParam) return '{' + renamedParam.n + '}'
           }
         }
       }
@@ -72,15 +72,15 @@ const TestDirect = cmp(function TestDirect(props: any) {
   const listOp = (entity.op as any)?.list
 
   const loadPoint = loadOp?.points?.[0]
-  const loadPath = loadPoint ? normalizePathParams(pointParts(loadPoint), loadPoint?.args?.params || [], loadPoint?.rename?.param) : ''
-  const allLoadParams = loadPoint?.args?.params || []
+  const loadPath = loadPoint ? normalizePathParams(pointParts(loadPoint), loadPoint?.g?.params || [], loadPoint?.r?.param) : ''
+  const allLoadParams = loadPoint?.g?.params || []
   const _pathPlaceholders = new Set<string>()
   for (const part of pointParts(loadPoint)) {
     if (typeof part === 'string' && part.startsWith('{') && part.endsWith('}')) {
       _pathPlaceholders.add(part.slice(1, -1))
     }
   }
-  const _renameMap = (loadPoint?.rename?.param || {}) as Record<string, string>
+  const _renameMap = (loadPoint?.r?.param || {}) as Record<string, string>
   const _renamedPlaceholders = new Set<string>()
   for (const ph of _pathPlaceholders) {
     _renamedPlaceholders.add(ph)
@@ -89,11 +89,11 @@ const TestDirect = cmp(function TestDirect(props: any) {
     }
   }
   const loadParams = allLoadParams.filter((p: any) =>
-    _renamedPlaceholders.has(p.name) || _renamedPlaceholders.has(p.orig))
+    _renamedPlaceholders.has(p.n) || _renamedPlaceholders.has(p.or))
 
   const listPoint = listOp?.points?.[0]
-  const listPath = listPoint ? normalizePathParams(pointParts(listPoint), listPoint?.args?.params || [], listPoint?.rename?.param) : ''
-  const listParams = listPoint?.args?.params || []
+  const listPath = listPoint ? normalizePathParams(pointParts(listPoint), listPoint?.g?.params || [], listPoint?.r?.param) : ''
+  const listParams = listPoint?.g?.params || []
 
   const evar = cppVarName(entity.name)
 
@@ -160,7 +160,7 @@ static void ${evar}_direct_list() {
 `)
       listParams.forEach((p: any, i: number) => {
         const placeholder = 'direct0' + (i + 1)
-        Content(`  setp(params, "${p.name}", Value("${placeholder}"));
+        Content(`  setp(params, "${p.n}", Value("${placeholder}"));
 `)
       })
       Content(`
@@ -207,7 +207,7 @@ static void ${evar}_direct_load() {
 `)
       loadParams.forEach((p: any, i: number) => {
         const placeholder = 'direct0' + (i + 1)
-        Content(`  setp(params, "${p.name}", Value("${placeholder}"));
+        Content(`  setp(params, "${p.n}", Value("${placeholder}"));
 `)
       })
       Content(`