@voxgig/sdkgen 4.19.1 → 4.21.0

package/project/.sdk/src/cmp/clojure/PrepareAuth_clojure.ts

@@ -0,0 +1,374 @@
+import {
+  Content,
+  File,
+  cmp,
+  isHttpBasicAuth,
+  resolveAuthIn,
+  resolveAuthName,
+  resolveAuthPrefix,
+} from '@voxgig/sdkgen'
+
+
+import {
+  KIT,
+  Model,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
+// rather than templated. The clojure port of cmp/ts/PrepareAuth_ts.ts; see
+// that file for 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, so the SDK sent a header the API does not
+// read and never sent the query parameter it does. Four repos in the cedar
+// fleet ship that way: joplin (`token`), pipedrive (`api_token`), trello
+// (`key`), lm-umbrella (`apiKey`).
+//
+// CLOJURE HAD NO prepare_auth TEMPLATE TO REPLACE. The other twelve targets
+// each had a standalone file; here the logic was EMBEDDED in
+// tm/clojure/src/sdk/core.clj as `u-prepare-auth`, three constants above it,
+// and the `:prepare-auth u-prepare-auth` entry in `base-utility-map`.
+//
+// THE EXTRACTION SHAPE: its own FILE, still inside the sdk.core NAMESPACE.
+//
+// A separate namespace is not available, and not for a stylistic reason.
+// `u-prepare-auth` calls `oget`, `ctx-error` and `client-options-map`, all
+// defined in sdk.core, while sdk.core's `base-utility-map` must reference
+// `u-prepare-auth` — so `(:require [sdk.prepare-auth])` from sdk.core plus
+// `(:require [sdk.core])` back is a load cycle, which Clojure refuses
+// outright ("Cyclic load dependency"). The alternatives are worse: passing
+// four core functions in as arguments, or late-binding through an atom the
+// way kotlin's `lateinit var prepareAuth` does, would both restructure the
+// runtime to work around a problem Clojure already has an answer for.
+//
+// That answer is `load`, the idiom clojure.core itself uses to split across
+// files (core.clj does `(load "core_deftype")`, `(load "core_print")`, …).
+// The generated file opens with `(in-ns 'sdk.core)` and is READ INTO sdk.core
+// at the exact point the defn used to sit, so:
+//
+//   - every helper it calls is already defined above it, unchanged;
+//   - the symbol `u-prepare-auth` resolves in `base-utility-map` exactly as
+//     before, so the `:prepare-auth` binding is untouched;
+//   - `core/HEADER-AUTH`, which feature/secrets/sdk/feature/secrets.clj
+//     reads, is still a public var of sdk.core;
+//   - and the call sites — `(ucall ctx :prepare-auth)` in core.clj's
+//     `u-make-spec`, `((core/uget ctx :prepare-auth) ctx)` in client.clj's
+//     `prepare`, and the same spelling in test/sdk/test/pipeline.clj and
+//     test/sdk/test/primary.clj — all still go through the utility map.
+//
+// A template cannot fix the defect, because the three placements need three
+// different bodies and a template has to pick one. This emits the branch the
+// API actually uses and nothing else — no dead query code in a bearer-token
+// SDK, and no runtime `if` on a value that is fixed at generation time.
+const PrepareAuth = cmp(async function PrepareAuth(props: any) {
+  const { target } = props
+  const model: Model = props.ctx$.model
+
+  // NO FOLDER IS OPENED HERE, and that is the whole of the placement
+  // decision. Main_clojure calls this inside its `Folder({name:'src'}) >
+  // Folder({name:'sdk'})` pair — the same pair Config sits in, and Config
+  // opens no folder of its own either. The file has to land beside the
+  // copied core.clj at `src/sdk/prepare_auth.clj`, because deps.edn declares
+  // `:paths ["src"]` and `(load "prepare_auth")` from the namespace sdk.core
+  // resolves to the CLASSPATH RESOURCE `sdk/prepare_auth.clj`. Opening a
+  // second `src`/`sdk` here would write `src/sdk/src/sdk/prepare_auth.clj`,
+  // which is not that resource.
+  File({ name: 'prepare_auth.' + target.ext }, () => {
+    Content(render({
+      Name: model.const.Name,
+      active: authSwitchedOn(model),
+      where: resolveAuthIn(model),
+      name: resolveAuthName(model),
+      basic: isHttpBasicAuth(model),
+      // Read so the resolution is visible at generation time even though the
+      // emitted code takes the prefix from options at runtime (the secrets
+      // feature rewrites it there).
+      prefix: resolveAuthPrefix(model),
+    }))
+  })
+})
+
+
+type AuthSpec = {
+  Name: string
+  active: boolean
+  where: string
+  name: string
+  basic: boolean
+  prefix: string
+}
+
+
+function render(spec: AuthSpec): string {
+  const head = `;; ${spec.Name} SDK: where the credential goes (generated by @voxgig/sdkgen).
+;;
+;; PART OF THE sdk.core NAMESPACE, not a namespace of its own: core.clj reads
+;; this file with \`(load "prepare_auth")\` at the point u-prepare-auth used to
+;; be defined, so oget / ctx-error / client-options-map are already in scope
+;; and base-utility-map's \`:prepare-auth u-prepare-auth\` still resolves.
+(in-ns 'sdk.core)
+
+`
+
+  if (!spec.active) return renderInactive(spec, head)
+
+  if ('query' === spec.where) return renderQuery(spec, head)
+  if ('cookie' === spec.where) return renderCookie(spec, head)
+
+  return renderHeader(spec, head)
+}
+
+
+// HEADER NAMES ARE LOWER-CASED; QUERY PARAMETER AND COOKIE NAMES ARE NOT.
+//
+// `resolveAuthName` answers 'Authorization' by default, but the whole clojure
+// runtime spells header names in lower case: the template this replaces held
+// `(def HEADER-AUTH "authorization")`, the shipped
+// test/sdk/test/feature/secrets.clj reads `(vs/getprop headers
+// "authorization")`, test/sdk/test/pipeline.clj asserts on the same key, and
+// the shared corpus asserts `ctx:spec:headers:authorization`. The spec's
+// headers are a java.util.LinkedHashMap, whose keys are case-SENSITIVE, so
+// emitting "Authorization" would put the credential under a key nothing
+// reads. HTTP header names are case-insensitive on the wire, so lower-casing
+// costs nothing. A query parameter and a cookie ARE case-sensitive (`?Token=`
+// is not `?token=`), so those go in verbatim.
+function headerName(name: string): string {
+  return String(name).toLowerCase()
+}
+
+
+// `core/HEADER-AUTH` IS PART OF sdk.core's PUBLIC SURFACE, so it is emitted
+// for every placement: feature/secrets/sdk/feature/secrets.clj writes the
+// re-authenticated credential with `(.put ^java.util.Map headers
+// core/HEADER-AUTH ...)`, and an SDK that resolves secrets would not compile
+// without the var.
+//
+// For a header scheme it is the header this SDK actually uses, so the two
+// writers agree by construction. For a query or cookie scheme the secrets
+// feature has no header of its own to name — its re-auth is an Authorization
+// rewrite, and the shipped suite asserts that literal — so the var keeps the
+// value it has always had rather than being pointed at a query parameter
+// name that means nothing in a header.
+function headerAuthConst(spec: AuthSpec): string {
+  return 'header' === spec.where ? headerName(spec.name) : 'authorization'
+}
+
+
+// HEADER. Byte-for-byte the block that was in core.clj when the scheme
+// resolves to the defaults (header / Authorization), so every header-based
+// SDK regenerates unchanged — only the constant's VALUE moves with the model,
+// plus the HTTP Basic branch, which is emitted only for a basic scheme.
+function renderHeader(spec: AuthSpec, head: string): string {
+  return head + `(def HEADER-AUTH ${cljstr(headerName(spec.name))})
+(def OPTION-APIKEY "apikey")
+` + (spec.basic ? `(def OPTION-SECRET "secret")
+` : '') + `(def NOT-FOUND "__NOTFOUND__")
+
+(defn u-prepare-auth [ctx]
+  (let [spec (oget ctx :spec)]
+    (if (nil? spec) [nil (ctx-error ctx "auth_no_spec" "Expected context spec property to be defined.")]
+        (let [headers (oget spec :headers)
+              options (client-options-map (oget ctx :client))]
+          (if (nil? (vs/getprop options "auth"))
+            ;; Public APIs that need no auth omit the options.auth block entirely.
+            (do (vs/delprop headers HEADER-AUTH) [spec nil])
+            (let [apikey (vs/getprop options OPTION-APIKEY NOT-FOUND)]
+${spec.basic ? basicBlock() : headerPlace(14)}
+              [spec nil]))))))
+`
+}
+
+
+// The template's own body, unchanged: an empty prefix (a raw apiKey
+// credential) must not add a leading space, and a missing credential deletes
+// whatever was there rather than leaving a stale value behind.
+function headerPlace(col: number): string {
+  const p = ' '.repeat(col)
+  return `${p}(if (or (nil? apikey) (and (string? apikey) (or (= apikey NOT-FOUND) (= apikey ""))))
+${p}  (vs/delprop headers HEADER-AUTH)
+${p}  (let [auth-prefix (or (vs/getpath options "auth.prefix") "")
+${p}        apikey-val (if (string? apikey) apikey "")]
+${p}    (.put ^java.util.Map headers HEADER-AUTH
+${p}          (if (= auth-prefix "") apikey-val (str auth-prefix " " apikey-val)))))`
+}
+
+
+// HTTP Basic is header-only by definition: the scheme is
+// `Authorization: Basic base64(user:pass)`. It cannot be expressed as a query
+// parameter or a cookie, so the branch is emitted only where it can mean
+// something — and only when the model says the scheme IS basic, so an
+// ordinary bearer SDK carries no dead code.
+function basicBlock(): string {
+  return `              ;; True HTTP Basic Auth needs TWO credentials, base64-joined - a
+              ;; single token in the header (the branch below) can never
+              ;; authenticate against an API that actually checks
+              ;; \`Authorization: Basic base64(user:pass)\`.
+              (if (= true (vs/getpath options "auth.basic"))
+                (let [secret (vs/getprop options OPTION-SECRET NOT-FOUND)
+                      missing? (fn [v] (or (nil? v)
+                                           (and (string? v) (or (= v NOT-FOUND) (= v "")))))]
+                  (if (or (missing? apikey) (missing? secret))
+                    (vs/delprop headers HEADER-AUTH)
+                    (let [auth-prefix (or (vs/getpath options "auth.prefix") "")
+                          b64 (.encodeToString (java.util.Base64/getEncoder)
+                                               (.getBytes ^String (str apikey ":" secret) "UTF-8"))]
+                      (.put ^java.util.Map headers HEADER-AUTH
+                            (if (= auth-prefix "") b64 (str auth-prefix " " b64))))))
+${headerPlace(16)})`
+}
+
+
+// QUERY. The credential is a query parameter, so it goes in the spec's query
+// map (which u-make-url turns into the query string) and the headers are
+// never touched.
+function renderQuery(spec: AuthSpec, head: string): string {
+  return head + `;; Retained for feature/secrets, whose re-auth writes an Authorization
+;; header; this SDK's own credential is a query parameter (see QUERY-AUTH).
+(def HEADER-AUTH ${cljstr(headerAuthConst(spec))})
+(def QUERY-AUTH ${cljstr(spec.name)})
+(def OPTION-APIKEY "apikey")
+(def NOT-FOUND "__NOTFOUND__")
+
+(defn u-prepare-auth [ctx]
+  (let [spec (oget ctx :spec)]
+    (if (nil? spec) [nil (ctx-error ctx "auth_no_spec" "Expected context spec property to be defined.")]
+        (let [query (oget spec :query)
+              options (client-options-map (oget ctx :client))]
+          (if (nil? (vs/getprop options "auth"))
+            ;; Public APIs that need no auth omit the options.auth block entirely.
+            (do (vs/delprop query QUERY-AUTH) [spec nil])
+            (let [apikey (vs/getprop options OPTION-APIKEY NOT-FOUND)]
+              (if (or (nil? apikey) (and (string? apikey) (or (= apikey NOT-FOUND) (= apikey ""))))
+                (vs/delprop query QUERY-AUTH)
+                (let [apikey-val (if (string? apikey) apikey "")]
+                  ;; NO PREFIX IN A QUERY STRING. \`?${spec.name}=Bearer%20abc\` is not a
+                  ;; thing any API reads: the prefix is a header convention, so it is
+                  ;; dropped here deliberately rather than silently concatenated.
+                  (.put ^java.util.Map query QUERY-AUTH apikey-val)))
+              [spec nil]))))))
+`
+}
+
+
+// COOKIE. 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
+// own pair is spliced in and out rather than the header being assigned over.
+// Splicing also makes this idempotent: a retried request cannot end up
+// carrying the credential twice.
+function renderCookie(spec: AuthSpec, head: string): string {
+  return head + `;; Retained for feature/secrets, whose re-auth writes an Authorization
+;; header; this SDK's own credential is a cookie (see COOKIE-AUTH).
+(def HEADER-AUTH ${cljstr(headerAuthConst(spec))})
+(def HEADER-COOKIE "cookie")
+(def COOKIE-AUTH ${cljstr(spec.name)})
+(def OPTION-APIKEY "apikey")
+(def NOT-FOUND "__NOTFOUND__")
+
+;; The cookie header minus our own pair, every other cookie left untouched.
+(defn- cookies-without-cred [headers]
+  (let [existing (vs/getprop headers HEADER-COOKIE)]
+    (if (or (not (string? existing)) (= "" existing))
+      ""
+      (str/join "; "
+                (remove (fn [piece]
+                          (or (= "" piece)
+                              (= COOKIE-AUTH piece)
+                              (str/starts-with? piece (str COOKIE-AUTH "="))))
+                        (map str/trim (str/split existing #";")))))))
+
+;; Set (a string) or remove (nil) our pair, leaving the rest in place.
+(defn- apply-cookie! [headers value]
+  (let [rest (cookies-without-cred headers)]
+    (if (nil? value)
+      (if (= "" rest)
+        (vs/delprop headers HEADER-COOKIE)
+        (.put ^java.util.Map headers HEADER-COOKIE rest))
+      (let [pair (str COOKIE-AUTH "=" value)]
+        (.put ^java.util.Map headers HEADER-COOKIE
+              (if (= "" rest) pair (str rest "; " pair)))))))
+
+(defn u-prepare-auth [ctx]
+  (let [spec (oget ctx :spec)]
+    (if (nil? spec) [nil (ctx-error ctx "auth_no_spec" "Expected context spec property to be defined.")]
+        (let [headers (oget spec :headers)
+              options (client-options-map (oget ctx :client))]
+          (if (nil? (vs/getprop options "auth"))
+            ;; Public APIs that need no auth omit the options.auth block entirely.
+            (do (apply-cookie! headers nil) [spec nil])
+            (let [apikey (vs/getprop options OPTION-APIKEY NOT-FOUND)]
+              (if (or (nil? apikey) (and (string? apikey) (or (= apikey NOT-FOUND) (= apikey ""))))
+                (apply-cookie! headers nil)
+                ;; NO PREFIX IN A COOKIE either - a cookie carries a bare
+                ;; \`name=value\` pair, not a header's scheme-prefixed credential.
+                (apply-cookie! headers (if (string? apikey) apikey "")))
+              [spec nil]))))))
+`
+}
+
+
+// NO AUTH AT ALL — the PROJECT switched it off (see authSwitchedOn for why
+// only an explicit switch counts). The SDK gets a u-prepare-auth that is
+// honest about it rather than one that deletes a header nobody set. The
+// function stays because core.clj's u-make-spec calls it unconditionally and
+// base-utility-map binds it unconditionally.
+function renderInactive(spec: AuthSpec, head: string): string {
+  return head + `;; This SDK is configured with authentication off
+;; (main.kit.config.auth.active: false), so there is no credential to place.
+;; HEADER-AUTH remains part of sdk.core's public surface because
+;; feature/secrets reads core/HEADER-AUTH.
+(def HEADER-AUTH ${cljstr(headerAuthConst(spec))})
+(def OPTION-APIKEY "apikey")
+(def NOT-FOUND "__NOTFOUND__")
+
+(defn u-prepare-auth [ctx]
+  (let [spec (oget ctx :spec)]
+    (if (nil? spec) [nil (ctx-error ctx "auth_no_spec" "Expected context spec property to be defined.")]
+        [spec nil])))
+`
+}
+
+
+// NOT `isAuthActive`, AND THE DIFFERENCE IS LOAD-BEARING (the py and rb ports
+// found this first; same reasoning, same fix).
+//
+// `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 — GitHub's official OpenAPI included, and
+// sdkgen's own generate fixture — and those SDKs are still expected to honour
+// an `apikey` the caller passes. core.clj's optspec ALWAYS declares `apikey`
+// and `auth`, and make-options fills `options.auth` from those defaults, so
+// the runtime `(nil? (vs/getprop options "auth"))` guard never fires and the
+// credential has always gone out.
+//
+// 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 prepare-auth then
+// places nothing. The shipped tm/clojure/test/sdk/test/feature/secrets.clj
+// suite, which sdkgen's own `clojure: the secrets feature runs with the
+// feature active` lane runs, is what catches it.
+//
+// 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 })
+  return !(null != auth && false === auth.active)
+}
+
+
+// A Clojure string literal. The reader's escapes are backslash-led, so only
+// the backslash and the double quote need handling.
+function cljstr(s: string): string {
+  return '"' + String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"'
+}
+
+
+export {
+  PrepareAuth
+}

package/project/.sdk/src/cmp/clojure/ReadmeExplanation_clojure.ts

@@ -23,6 +23,7 @@ ${target.name}/
 ├── src/sdk/api.clj        -- public API namespace (entity accessors)
 ├── src/sdk/client.clj     -- client constructors (make-sdk, test-sdk)
 ├── src/sdk/config.clj     -- generated configuration
+├── src/sdk/schema.clj     -- generated option + entity specs
 ├── src/sdk/core.clj       -- core types, context and pipeline
 ├── src/sdk/features.clj   -- feature factory
 ├── src/sdk/entity/        -- entity namespaces (one per entity)

package/project/.sdk/src/cmp/clojure/Schema_clojure.ts

@@ -0,0 +1,73 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+import {
+  cljStringChunks,
+} from './utility_clojure'
+
+
+// THE GENERATED SCHEMA NAMESPACE: the model's schemas, as data the SDK runs.
+//
+// The clojure peer of src/cmp/ts/Schema_ts.ts. Same source — OPTSPEC from
+// `main.kit.optspec` plus each feature's own `config.options`, ENTITYSPEC
+// from the entity field sentinels — built by the shared helpers, so what
+// clojure validates against and what ts validates against cannot drift.
+//
+// DATA ONLY, AND THAT IS STRUCTURAL. This namespace requires nothing and
+// exposes the raw JSON strings; `sdk.core` parses them. The parse it would
+// otherwise call, `json-parse`, is defined in sdk.core itself — and sdk.core
+// is what reads the spec — so a schema ns that required core to parse its own
+// data would close a require cycle. Holding the strings here and parsing
+// there is the only arrangement that does not.
+//
+// Chunked the way config.clj chunks its model: the JVM caps a string literal
+// at 64KB, so `cljStringChunks` splits and `str` rejoins at load.
+//
+// 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
+
+  const model: Model = ctx$.model
+
+  const optspec = optionSpec(model, target.name)
+  const entityspec = entitySpecMap(model, target.name) || {}
+
+  const chunks = (json: string) =>
+    cljStringChunks(json).map((c: string) => JSON.stringify(c)).join('\n       ')
+
+  File({ name: 'schema.clj' }, () => {
+    Content(`;; ${model.const.Name} ${target.Name} SDK: generated schemas. Do not edit.
+;;
+;; Generated from the model: main.kit.optspec and each feature's
+;; config.options for the option spec; entity fields[].type for the entity
+;; specs. Parsed by sdk.core — see the note in Schema_clojure.ts for why the
+;; parse cannot live here.
+(ns sdk.schema)
+
+(def optspec-data
+  (str ${chunks(JSON.stringify(optspec))}))
+
+(def entityspec-data
+  (str ${chunks(JSON.stringify(entityspec))}))
+`)
+  })
+})
+
+
+export {
+  Schema
+}

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

@@ -5,6 +5,9 @@ import {
   cmp,
   configDefinition,
   each,
+  isAuthActive,
+  resolveAuthIn,
+  resolveAuthName,
   targetFeatures,
 } from '@voxgig/sdkgen'
 
@@ -329,6 +332,43 @@ const Config = cmp(async function Config(props: any) {
   // story for this target.
   const { def: configDef } = configDefinition(model, target.name)
 
+  // `in` and `name` TRAVEL WITH THE PREFIX NOW.
+  //
+  // apidef resolved both from the spec's securityScheme all along and this
+  // generator dropped them, so an apiKey-in-query API got an `authorization`
+  // header it does not read (see PrepareAuth_cpp). The generated
+  // prepare_auth is built from the same two values, and the config carries
+  // them so the placement is a visible, overridable runtime option beside
+  // auth.prefix.
+  //
+  // IT IS INERT WITHOUT THE OPTSPEC. cpp does not build its option schema
+  // from the model: it is a JSON literal in tm/cpp/utility/pipeline.hpp
+  // (OPTSPEC_JSON), and cpp's vendored Struct::validate SILENTLY DROPS a key
+  // that literal does not declare rather than rejecting it. So the config
+  // written here reached makeOptions and was trimmed back to `prefix` on the
+  // way in, and prepareAuth read an `auth` map with no `in`, no `name` and
+  // no `basic` - measured on a generated client before the literal was
+  // extended. That literal now declares all three; changing only this file
+  // would have changed nothing a running SDK can see.
+  //
+  // Emitted ONLY when they differ from header/Authorization, so a
+  // header-based SDK's core/config.hpp is byte-identical to what it
+  // generated before. cpp has one representation - the chunked JSON literal
+  // rendered from this same def by cppConfigLiterals - so there is no second
+  // copy to keep in step.
+  const authIn = resolveAuthIn(model)
+  const authName = resolveAuthName(model)
+
+  if (isAuthActive(model) && null != configDef.options &&
+    null != configDef.options.auth) {
+    if ('header' !== authIn) {
+      configDef.options.auth.in = authIn
+    }
+    if ('Authorization' !== authName) {
+      configDef.options.auth.name = authName
+    }
+  }
+
   File({ name: 'config.' + target.ext }, () => {
 
     Content(`// Generated API configuration (mirrors Config_java / core/config.go).

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

@@ -23,10 +23,12 @@ import {
 
 import { Package } from './Package_cpp'
 import { Config, FeaturePlugins } from './Config_cpp'
+import { Schema } from './Schema_cpp'
 import { Gitignore } from './Gitignore_cpp'
 import { MainEntity } from './MainEntity_cpp'
 import { EntityBase } from './EntityBase_cpp'
 import { EntityTypes } from './EntityTypes_cpp'
+import { PrepareAuth } from './PrepareAuth_cpp'
 
 
 const Main = cmp(async function Main(props: any) {
@@ -111,6 +113,8 @@ const Main = cmp(async function Main(props: any) {
 
     Config({ target })
 
+    Schema({ target })
+
     // core/client.hpp — the generated client class with entity accessors.
     File({ name: 'client.' + target.ext }, () => {
 
@@ -134,6 +138,22 @@ const Main = cmp(async function Main(props: any) {
     })
   })
 
+  // utility/prepare_auth.hpp is GENERATED, not templated: where the
+  // credential goes (header / query / cookie, and under what name) is a fact
+  // about the API, and tm/ can only hold one answer. See PrepareAuth_cpp.
+  //
+  // cpp had no prepare_auth template to replace - the logic was EMBEDDED in
+  // tm/cpp/utility/pipeline.hpp. It now lives in its own header, which
+  // pipeline.hpp includes; register_all still binds
+  // `u.prepareAuth = util::prepareAuth`, so every call site is unchanged.
+  //
+  // AT ROOT LEVEL, and OUTSIDE the `core` Folder above. The component opens
+  // `utility` itself, mirroring where `Copy({from:'tm/cpp'})` lands
+  // utility/pipeline.hpp; calling it beside Config would write
+  // `core/utility/prepare_auth.hpp`, which pipeline.hpp's
+  // `#include "prepare_auth.hpp"` does not resolve.
+  PrepareAuth({ target })
+
   // feature/<name>/kinds.cpp — the plugin definitions an active
   // plugin-bearing feature selected, and the Makefile's wiring gate for that
   // feature's vendored payload (see Config_cpp). Nothing is emitted when no