@voxgig/sdkgen 4.19.0 → 4.20.0

package/project/.sdk/tm/ocaml/test/t_pipeline.ml

@@ -308,13 +308,71 @@ let () =
       ignore (u.u_fetcher ctx "http://h/a" (jo [("method", Str "GET"); ("headers", empty_map ())]));
       check "order" (!order = ["second"; "first"; "server"]));
 
+  (* prepare_auth IS GENERATED (Sdk_prepare_auth), so these four cases ask
+   * the generated module where this SDK puts its credential instead of
+   * assuming a header. They used to read `spec.headers["authorization"]`
+   * outright, which made them pass only for a header scheme and FAIL on
+   * every apiKey-in-query SDK - joplin's `?token=` - i.e. on exactly the
+   * SDKs the model-driven placement exists to make work. The assertions
+   * still drive the real u_prepare_auth end to end and check the bag, the
+   * key and the value it actually wrote; only the expectation is read from
+   * the SDK's own declared contract rather than hardcoded. *)
+  let auth_bag (ctx : ctx) : value =
+    let sp = match ctx.c_spec with Some s -> s | None -> assert false in
+    if Sdk_prepare_auth.cred_where = "query" then sp.sp_query else sp.sp_headers in
+
+  (* A cookie rides the shared `cookie` header, so the KEY is that header and
+   * the VALUE is a `name=value` pair. A header and a query parameter are
+   * keyed by the credential name itself. *)
+  let auth_key =
+    if Sdk_prepare_auth.cred_where = "cookie" then "cookie"
+    else Sdk_prepare_auth.cred_name in
+
+  (* A header carries the auth.prefix, space-joined when it is non-empty. A
+   * query parameter and a cookie do NOT: `?token=Bearer%20abc` is not a
+   * thing any API reads. *)
+  let auth_placed (prefix : string) (cred : string) : string =
+    if Sdk_prepare_auth.cred_where = "query" then cred
+    else if Sdk_prepare_auth.cred_where = "cookie" then
+      Sdk_prepare_auth.cred_name ^ "=" ^ cred
+    else if prefix <> "" then prefix ^ " " ^ cred
+    else cred in
+
+  (* An SDK built with main.kit.config.auth.active: false places nothing at
+   * all, by design, so the two placement cases assert the absence instead. *)
+  let check_placed (label : string) (ctx : ctx) (prefix : string) (cred : string) =
+    if Sdk_prepare_auth.cred_active then
+      check_vstr label (getp (auth_bag ctx) auth_key) (auth_placed prefix cred)
+    else
+      check (label ^ ": auth off, nothing placed")
+        (is_noval (getp (auth_bag ctx) auth_key)) in
+
+  (* The stale credential a clearing case must remove, written the way
+   * prepare_auth would have written it - a bare value for a header or a
+   * query parameter, a `name=value` pair for a cookie, since cookie_set
+   * splices OUR pair out and leaves every other cookie alone. *)
+  let stale_spec () : spec =
+    let placed = Str (auth_placed "" "stale") in
+    if Sdk_prepare_auth.cred_where = "query" then
+      new_spec (jo [("headers", empty_map ()); ("query", jo [(auth_key, placed)])])
+    else
+      new_spec (jo [("headers", jo [(auth_key, placed)])]) in
+
+  (* With auth switched off nothing is removed either: the function is a
+   * no-op by design, so a stale value is expected to survive. *)
+  let check_cleared (label : string) (ctx : ctx) =
+    let got = getp (auth_bag ctx) auth_key in
+    if Sdk_prepare_auth.cred_active then check label (is_noval got)
+    else check (label ^ ": auth off, nothing touched")
+        (got = Str (auth_placed "" "stale")) in
+
   test "prepare_auth.apikey_prefix_space_joined" (fun () ->
       let cl = client () in
       let ctx = mk_ctx cl "load" in
       cl.cl_options <- jo [("apikey", Str "K"); ("auth", jo [("prefix", Str "Bearer")])];
       ctx.c_spec <- Some (new_spec (jo [("headers", empty_map ())]));
       ignore (cl.cl_utility.u_prepare_auth ctx);
-      check_vstr "auth" (getp (match ctx.c_spec with Some s -> s.sp_headers | None -> Noval) "authorization") "Bearer K");
+      check_placed "auth" ctx "Bearer" "K");
 
   test "prepare_auth.raw_apikey" (fun () ->
       let cl = client () in
@@ -322,23 +380,23 @@ let () =
       cl.cl_options <- jo [("apikey", Str "K"); ("auth", jo [("prefix", Str "")])];
       ctx.c_spec <- Some (new_spec (jo [("headers", empty_map ())]));
       ignore (cl.cl_utility.u_prepare_auth ctx);
-      check_vstr "auth" (getp (match ctx.c_spec with Some s -> s.sp_headers | None -> Noval) "authorization") "K");
+      check_placed "auth" ctx "" "K");
 
   test "prepare_auth.empty_apikey_drops_header" (fun () ->
       let cl = client () in
       let ctx = mk_ctx cl "load" in
       cl.cl_options <- jo [("apikey", Str ""); ("auth", jo [("prefix", Str "Bearer")])];
-      ctx.c_spec <- Some (new_spec (jo [("headers", jo [("authorization", Str "stale")])]));
+      ctx.c_spec <- Some (stale_spec ());
       ignore (cl.cl_utility.u_prepare_auth ctx);
-      check "dropped" (is_noval (getp (match ctx.c_spec with Some s -> s.sp_headers | None -> Noval) "authorization")));
+      check_cleared "dropped" ctx);
 
   test "prepare_auth.no_auth_block_drops_header" (fun () ->
       let cl = client () in
       let ctx = mk_ctx cl "load" in
       cl.cl_options <- jo [("apikey", Str "K")];
-      ctx.c_spec <- Some (new_spec (jo [("headers", jo [("authorization", Str "stale")])]));
+      ctx.c_spec <- Some (stale_spec ());
       ignore (cl.cl_utility.u_prepare_auth ctx);
-      check "dropped" (is_noval (getp (match ctx.c_spec with Some s -> s.sp_headers | None -> Noval) "authorization")));
+      check_cleared "dropped" ctx);
 
   test "result_headers.no_headers_empty_map" (fun () ->
       let cl = client () in

package/project/.sdk/tm/perl/utility/make_options.pm

@@ -128,7 +128,16 @@ $REGISTRY{make_options} = sub {
     'suffix' => '',
     # `basic` and `secret`: HTTP Basic Auth needs a second credential and a
     # flag to say the pair is Basic rather than a single bearer token.
-    'auth' => { 'prefix' => '', 'basic' => $JF },
+    #
+    # `in` and `name`: WHERE the credential goes and UNDER WHAT NAME -
+    # header (the default, `authorization`), query or cookie. This shape
+    # is CLOSED, so a config carrying a key it does not list makes every
+    # request fail validation: without these two entries an
+    # apiKey-in-query SDK (joplin's `?token=`) could not build its
+    # options at all. They mirror main.kit.optspec.auth, which the
+    # model-driven targets read directly, and '' means "whatever the
+    # spec resolved", which is what prepare_auth already baked in.
+    'auth' => { 'prefix' => '', 'basic' => $JF, 'in' => '', 'name' => '' },
     'headers' => { '`$CHILD`' => '`$STRING`' },
     'allow' => {
       'method' => 'GET,PUT,POST,PATCH,DELETE,OPTIONS',

package/project/.sdk/tm/php/utility/MakeOptions.php

@@ -153,7 +153,14 @@ class ProjectNameMakeOptions
             'base' => 'http://localhost:8000',
             'prefix' => '',
             'suffix' => '',
-            'auth' => ['prefix' => '', 'basic' => false],
+            // `in` and `name` say WHERE the credential goes and under what
+            // name (header | query | cookie). The generated config carries
+            // them whenever the spec's scheme is not the header/Authorization
+            // default, and validate REJECTS a key this spec does not declare,
+            // so an apiKey-in-query SDK cannot be constructed without them.
+            // '' means "take what the spec said", which is what prepare_auth
+            // was generated from.
+            'auth' => ['prefix' => '', 'basic' => false, 'in' => '', 'name' => ''],
             'headers' => ['`$CHILD`' => '`$STRING`'],
             'allow' => [
                 'method' => 'GET,PUT,POST,PATCH,DELETE,OPTIONS',

package/project/.sdk/tm/rust/utility/make_options.rs

@@ -78,7 +78,19 @@ pub fn make_options_util(ctx: &Rc<Context>) -> Value {
         ("base", Value::str("http://localhost:8000")),
         ("prefix", Value::str("")),
         ("suffix", Value::str("")),
-        ("auth", jo(vec![("prefix", Value::str("")), ("basic", Value::Bool(false))])),
+        // CLOSED - validate rejects any key it does not declare - so without
+        // `in` and `name` an apiKey-in-query SDK fails to construct on its
+        // own config with "Unexpected keys at field auth: in, name".
+        // '' means "take what the spec said".
+        (
+            "auth",
+            jo(vec![
+                ("prefix", Value::str("")),
+                ("basic", Value::Bool(false)),
+                ("in", Value::str("")),
+                ("name", Value::str("")),
+            ]),
+        ),
         ("headers", jo(vec![("`$CHILD`", Value::str("`$STRING`"))])),
         (
             "allow",

package/project/.sdk/tm/scala/utility/Make.scala

@@ -306,10 +306,23 @@ object MakeOptions {
     val optspec = Json.parse(
       "{"
         + "\"apikey\": \"\","
+        // The SECOND credential, for the HTTP Basic scheme
+        // (base64(apikey:secret)). Named by main.kit.optspec but missing
+        // here, and validate drops what it does not name - so a caller
+        // that supplied `secret` never had it reach prepareAuth.
+        + "\"secret\": \"\","
         + "\"base\": \"http://localhost:8000\","
         + "\"prefix\": \"\","
         + "\"suffix\": \"\","
-        + "\"auth\": { \"prefix\": \"\" },"
+        // WHERE the credential goes and under what name, plus the HTTP
+        // Basic switch. `Struct.validate` DROPS a key this spec does not
+        // name, so without these three the generated Config's auth block
+        // was trimmed back to `prefix` on the way in and the SDK could not
+        // see its own scheme - which made Config_scala's `in`/`name`
+        // emission inert. Mirrors main.kit.optspec.auth in
+        // @voxgig/sdkgen/model/sdkgen.aon, which ts builds its OPTSPEC from.
+        + "\"auth\": { \"prefix\": \"\", \"basic\": false,"
+        + "          \"in\": \"\", \"name\": \"\" },"
         + "\"headers\": { \"`$CHILD`\": \"`$STRING`\" },"
         + "\"allow\": {"
         + "  \"method\": \"GET,PUT,POST,PATCH,DELETE,OPTIONS\","

package/project/.sdk/tm/scala/utility/Prepare.scala

@@ -108,43 +108,19 @@ object PrepareBody {
     if ("data" == ctx.op.input) ctx.utility.transformRequest(ctx) else null
 }
 
-object PrepareAuth {
-  val HEADER_AUTH = "authorization"
-  val OPTION_APIKEY = "apikey"
-  val NOT_FOUND = "__NOTFOUND__"
-
-  def prepareAuth(ctx: Context): Spec = {
-    val spec = ctx.spec
-    if (spec == null) throw ctx.makeError("auth_no_spec", "Expected context spec property to be defined.")
-
-    val headers = spec.headers
-    val options = ctx.client.optionsMap()
-
-    // Public APIs that need no auth omit the options.auth block entirely.
-    if (options.get("auth") == null) {
-      headers.remove(HEADER_AUTH)
-      return spec
-    }
-
-    val apikey = Struct.getprop(options, OPTION_APIKEY, NOT_FOUND)
-
-    var skip = false
-    if (apikey == null) skip = true
-    else apikey match {
-      case s: String if NOT_FOUND == s || "" == s => skip = true
-      case _ =>
-    }
-
-    if (skip) {
-      headers.remove(HEADER_AUTH)
-    } else {
-      var authPrefix = ""
-      Struct.getpath(options, java.util.List.of("auth", "prefix")) match { case s: String => authPrefix = s; case _ => }
-      val apikeyVal = apikey match { case s: String => s; case _ => "" }
-      if ("" == authPrefix) headers.put(HEADER_AUTH, apikeyVal)
-      else headers.put(HEADER_AUTH, authPrefix + " " + apikeyVal)
-    }
-
-    spec
-  }
-}
+// NO `object PrepareAuth` HERE, and its absence is the point.
+//
+// WHERE the credential goes is a fact about the API - header, query or
+// cookie, under the name the spec gives - and apidef resolves all of it
+// into main.kit.info.security. This file can hold only ONE answer, so the
+// object that used to sit here hardcoded `val HEADER_AUTH = "authorization"`
+// and an apiKey-in-query API (joplin's `?token=`) got a header it ignores.
+//
+// So prepareAuth is GENERATED, into utility/PrepareAuth.scala beside this
+// file, by src/cmp/scala/PrepareAuth_scala.ts - which emits the one branch
+// this API actually uses. It stays `object PrepareAuth` in this same
+// package, so utility/Register.scala's `u.prepareAuth = (ctx) =>
+// PrepareAuth.prepareAuth(ctx)` binds it with no change: scala resolves the
+// object by package, not by file name.
+//
+// The six objects above are placement-independent and stay templated.

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/utility/MakeOptions.swift

@@ -4,8 +4,30 @@
 import Foundation
 
 private func buildOptSpec() -> Value {
-  let authPrefix = VMap()
-  authPrefix.entries["prefix"] = .string("")
+  // THE AUTH OPTION BLOCK, and every key the generated config can put in it.
+  //
+  // This spec is what `validate` checks the merged options against, and a key
+  // it does not name does not survive - so the generated Config's auth block
+  // was trimmed back to `prefix` on the way in and the SDK could not see its
+  // own scheme.
+  //
+  //   prefix  the credential prefix (Bearer/Basic/OAuth, or '' for a raw key)
+  //   basic   the scheme is real HTTP Basic: base64(apikey:secret), not a
+  //           single bearer token
+  //   in      WHERE the credential goes: header (the default) | query | cookie
+  //   name    the header, query parameter or cookie name it goes in under
+  //
+  // `in` and `name` mirror main.kit.optspec.auth in
+  // @voxgig/sdkgen/model/sdkgen.aon, which the model-driven targets read
+  // directly; '' means "take what the spec said", which is what the generated
+  // prepareAuth was built from, so an SDK that sets neither behaves exactly as
+  // it did before. Without them an apiKey-in-query SDK (joplin's `?token=`)
+  // cannot even construct its own options.
+  let authSpec = VMap()
+  authSpec.entries["prefix"] = .string("")
+  authSpec.entries["basic"] = .bool(false)
+  authSpec.entries["in"] = .string("")
+  authSpec.entries["name"] = .string("")
 
   let headers = VMap()
   headers.entries["`$CHILD`"] = .string("`$STRING`")
@@ -38,10 +60,15 @@ private func buildOptSpec() -> Value {
 
   let spec = VMap()
   spec.entries["apikey"] = .string("")
+  // The SECOND credential, for the HTTP Basic scheme
+  // (base64(apikey:secret)). Named by main.kit.optspec but missing here, and
+  // validate does not pass what it does not name - so a caller that supplied
+  // `secret` never had it reach prepareAuth.
+  spec.entries["secret"] = .string("")
   spec.entries["base"] = .string("http://localhost:8000")
   spec.entries["prefix"] = .string("")
   spec.entries["suffix"] = .string("")
-  spec.entries["auth"] = .map(authPrefix)
+  spec.entries["auth"] = .map(authSpec)
   spec.entries["headers"] = .map(headers)
   spec.entries["allow"] = .map(allow)
   spec.entries["entity"] = .map(entity)

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/utility/Prepare.swift

@@ -1,5 +1,6 @@
 // ProjectName SDK utility: request preparation steps (method, path, params,
-// query, headers, body, auth) plus param resolution.
+// query, headers, body) plus param resolution. The auth step is GENERATED
+// into utility/PrepareAuth.swift - see the note below.
 
 import Foundation
 
@@ -89,44 +90,25 @@ func prepareBodyUtil(_ ctx: Context) -> Value {
   return .noval
 }
 
-private let headerAuth = "authorization"
-private let optionApikey = "apikey"
-private let notFound = "__NOTFOUND__"
-
-func prepareAuthUtil(_ ctx: Context) throws -> Spec {
-  guard let spec = ctx.spec else {
-    throw ctx.makeError("auth_no_spec", "Expected context spec property to be defined.")
-  }
-
-  let headers = spec.headers
-  let options = ctx.client!.optionsMap()
-
-  // Public APIs that need no auth omit the options.auth block entirely.
-  let auth = getprop(.map(options), .string("auth"))
-  if isNil(auth) {
-    headers.entries.removeValue(forKey: headerAuth)
-    return spec
-  }
-
-  let apikey = getprop(.map(options), .string(optionApikey), .string(notFound))
-
-  var skip = isNil(apikey)
-  if let apikeyStr = apikey.asString, apikeyStr == notFound || apikeyStr == "" {
-    skip = true
-  }
-
-  if skip {
-    headers.entries.removeValue(forKey: headerAuth)
-  } else {
-    var authPrefix = ""
-    if let ap = gpath(options, "auth", "prefix").asString { authPrefix = ap }
-    let apikeyVal = apikey.asString ?? ""
-    // Empty prefix (raw apiKey credential) must not add a leading space.
-    headers.entries[headerAuth] = .string(authPrefix == "" ? apikeyVal : authPrefix + " " + apikeyVal)
-  }
-
-  return spec
-}
+// prepareAuth IS NOT HERE. It was, and it hardcoded
+//
+//   private let headerAuth = "authorization"
+//
+// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API - header, query or
+// cookie, and under what name - and apidef resolves it into
+// main.kit.info.security. A template can only hold one answer, so an
+// apiKey-in-query API (joplin's `?token=`) got an Authorization header it
+// does not read and never got the query parameter it does.
+//
+// So `prepareAuthUtil` is GENERATED, into utility/PrepareAuth.swift beside
+// this file, by cmp/swift/PrepareAuth_swift.ts. Same module, same internal
+// symbol, so utility/Register.swift still binds it with
+// `u.prepareAuth = prepareAuthUtil` and nothing else moved. Declaring it
+// here as well would be an "invalid redeclaration" that fails the whole
+// SwiftPM target.
+//
+// The seven functions above and paramUtil below do not depend on the model,
+// so they stay templated.
 
 func paramUtil(_ ctx: Context, _ paramdef: Value) -> Value {
   let point = ctx.point

package/project/.sdk/tm/zig/core/utility.zig

@@ -372,7 +372,18 @@ pub fn make_options_util(ctx: *Context) Value {
         .{ "base", h.vstr("http://localhost:8000") },
         .{ "prefix", h.vstr("") },
         .{ "suffix", h.vstr("") },
-        .{ "auth", h.jo(&.{ .{ "prefix", h.vstr("") }, .{ "basic", h.vbool(false) } }) },
+        // CLOSED - validate REJECTS any key this spec does not declare - so
+        // without `in` and `name` an apiKey-in-query SDK fails validation on
+        // its OWN generated config (Config_zig emits them whenever the
+        // scheme is not the header/Authorization default), and the whole
+        // merged options object is discarded. '' means "take what the spec
+        // said", which is what the generated prepare_auth was built from.
+        .{ "auth", h.jo(&.{
+            .{ "prefix", h.vstr("") },
+            .{ "basic", h.vbool(false) },
+            .{ "in", h.vstr("") },
+            .{ "name", h.vstr("") },
+        }) },
         .{ "headers", h.jo(&.{.{ "`$CHILD`", h.vstr("`$STRING`") }}) },
         .{ "allow", h.jo(&.{
             .{ "method", h.vstr("GET,PUT,POST,PATCH,DELETE,OPTIONS") },
@@ -1308,50 +1319,31 @@ pub fn graphql_errors_util(ctx: *Context) bool {
     return true;
 }
 
-const HEADER_AUTH = "authorization";
-const OPTION_APIKEY = "apikey";
-const NOT_FOUND = "__NOTFOUND__";
-
-pub fn prepare_auth_util(ctx: *Context) E!*Spec {
-    const spec = ctx.spec orelse return ctx.fail("auth_no_spec", "Expected context spec property to be defined.");
-
-    const headers = spec.headers;
-    const options: Value = if (ctx.client) |client| client.options_map() else ctx.options;
-
-    const auth = h.getp(options, "auth");
-    if (h.is_noval(auth)) {
-        h.del_prop(headers, h.vstr(HEADER_AUTH));
-        return spec;
-    }
-
-    const apikey = vs.getprop(h.A(), options, h.vstr(OPTION_APIKEY), h.vstr(NOT_FOUND)) catch h.vstr(NOT_FOUND);
-
-    const skip = switch (apikey) {
-        .null => true,
-        .string => |s| std.mem.eql(u8, s, NOT_FOUND) or s.len == 0,
-        else => false,
-    };
-
-    if (skip) {
-        h.del_prop(headers, h.vstr(HEADER_AUTH));
-    } else {
-        const auth_prefix: []const u8 = switch (h.getpath(&.{ "auth", "prefix" }, options)) {
-            .string => |s| s,
-            else => "",
-        };
-        const apikey_val: []const u8 = switch (apikey) {
-            .string => |s| s,
-            else => "",
-        };
-        if (auth_prefix.len == 0) {
-            h.setp(headers, HEADER_AUTH, h.vstr(apikey_val));
-        } else {
-            h.setp(headers, HEADER_AUTH, h.vstr(fmt("{s} {s}", .{ auth_prefix, apikey_val })));
-        }
-    }
-
-    return spec;
-}
+// prepare_auth IS GENERATED (src/cmp/zig/PrepareAuth_zig.ts), not templated.
+//
+// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API. apidef resolves the
+// security scheme's `in` and `name` into main.kit.info.security - joplin's
+// says `in: "query", name: "token"` - and this file could hold only one
+// answer, which was `const HEADER_AUTH = "authorization"`. So an
+// apiKey-in-query API was sent a header it does not read and never sent the
+// query parameter it does. Header, query and cookie need three different
+// bodies; a component emits the one this API uses and nothing else.
+//
+// RE-EXPORTED, NOT REWIRED. Every caller keeps naming the same symbol:
+// `Utility.prepare_auth` above, `make_spec_util`'s unqualified
+// `try prepare_auth_util(ctx)`, and `sdk.utilmod.prepare_auth_util` - the
+// path root.zig publishes and test/primary_utility_test.zig drives the
+// shared corpus's `prepareAuth` section through. A file-scope const bound to
+// the generated function is the whole of the binding change.
+pub const prepare_auth_util = @import("prepare_auth.zig").prepare_auth_util;
+
+// The two comptime FACTS the generated file decided: where this SDK puts its
+// credential ("header" | "query" | "cookie" | "none"), and whether the scheme
+// is genuine HTTP Basic. Re-exported on the same path as the function, so
+// test/pipeline_test.zig can reach both as `sdk.utilmod.<name>` and skip the
+// header-shape cases on an SDK that has no header credential to assert on.
+pub const prepare_auth_placement = @import("prepare_auth.zig").PLACEMENT;
+pub const prepare_auth_basic = @import("prepare_auth.zig").BASIC;
 
 pub fn result_basic_util(ctx: *Context) ?*SdkResult {
     const response = ctx.response;

package/project/.sdk/tm/zig/test/pipeline_test.zig

@@ -367,6 +367,35 @@ test "pipeline feature_add: ordering before after replace" {
 // prepare_auth
 // =====================================================================
 
+// WHERE THE CREDENTIAL GOES IS MODEL-DRIVEN: core/prepare_auth.zig is
+// GENERATED from the API's security scheme, and has exactly one branch. The
+// cases below assert the HEADER shape - a key in `spec.headers` named
+// `authorization` - which is the right assertion for the default and the
+// wrong one for the other three. An SDK whose scheme puts the credential in
+// the query string (`?token=`) or a cookie, and one whose project set
+// `main.kit.config.auth.active: false`, correctly place NOTHING in the header
+// bag, so these would go red for a reason that is not a defect.
+//
+// The generated file exports what it chose as a COMPTIME constant, and
+// core/utility.zig re-exports it. Not read from the options: a query SDK's
+// `options.auth.in` does say "query", but an auth-OFF SDK looks exactly like
+// a header one there - Config omits `options.auth` entirely when auth is
+// inactive and the optspec then supplies the same empty defaults.
+//
+// A header SDK - every SDK whose scheme resolves to the default - runs all of
+// these exactly as it did before prepare_auth became a component.
+fn headerCred() bool {
+    return std.mem.eql(u8, sdk.utilmod.prepare_auth_placement, "header");
+}
+
+// The two cases that assert how a single token is SHAPED into the header
+// value need more than a header placement: genuine HTTP Basic replaces that
+// shaping with base64(apikey:secret), and refuses outright when the secret is
+// missing - which is exactly what those two fixtures leave out.
+fn singleTokenCred() bool {
+    return headerCred() and !sdk.utilmod.prepare_auth_basic;
+}
+
 test "pipeline prepare_auth: guards missing spec" {
     const client = sdk.test_sdk(vnull(), h.jo(&.{.{ "apikey", h.vstr("K") }}));
     const utility = client.get_utility();
@@ -381,6 +410,7 @@ test "pipeline prepare_auth: apikey with prefix space joined" {
         .{ "apikey", h.vstr("K") },
         .{ "auth", h.jo(&.{.{ "prefix", h.vstr("Bearer") }}) },
     }));
+    if (!singleTokenCred()) return;
     const utility = client.get_utility();
     const ctx = plCtx(client, utility, null);
     ctx.spec = authSpec(vnull());
@@ -393,6 +423,7 @@ test "pipeline prepare_auth: raw apikey empty prefix as is" {
         .{ "apikey", h.vstr("K") },
         .{ "auth", h.jo(&.{.{ "prefix", h.vstr("") }}) },
     }));
+    if (!singleTokenCred()) return;
     const utility = client.get_utility();
     const ctx = plCtx(client, utility, null);
     ctx.spec = authSpec(vnull());
@@ -405,6 +436,7 @@ test "pipeline prepare_auth: empty apikey drops header" {
         .{ "apikey", h.vstr("") },
         .{ "auth", h.jo(&.{.{ "prefix", h.vstr("Bearer") }}) },
     }));
+    if (!headerCred()) return;
     const utility = client.get_utility();
     const ctx = plCtx(client, utility, null);
     ctx.spec = authSpec(h.jo(&.{.{ "authorization", h.vstr("stale") }}));
@@ -416,6 +448,7 @@ test "pipeline prepare_auth: missing apikey drops header" {
     const client = sdk.test_sdk(vnull(), h.jo(&.{
         .{ "auth", h.jo(&.{.{ "prefix", h.vstr("Bearer") }}) },
     }));
+    if (!headerCred()) return;
     const utility = client.get_utility();
     const options = client.options_map();
     // Skip if this SDK's options happen to carry a configured apikey.
@@ -430,6 +463,7 @@ test "pipeline prepare_auth: missing apikey drops header" {
 
 test "pipeline prepare_auth: public api no auth block drops header" {
     const client = sdk.test_sdk(vnull(), h.jo(&.{.{ "apikey", h.vstr("K") }}));
+    if (!headerCred()) return;
     const utility = client.get_utility();
     // Option validation supplies an auth shape for this SDK, so a truly
     // auth-less client cannot be constructed here — mirror the rust skip.

package/project/sdkgen-package.json

@@ -3,7 +3,7 @@
     "package": 1
   },
   "name": "@voxgig/sdkgen",
-  "version": "4.19.0",
+  "version": "4.20.0",
   "provides": {
     "target": [
       "c",

package/src/cmp/AgentGuideContent.ts

@@ -274,7 +274,7 @@ syntax) with unification semantics:
 | \`*default \\| type\` | A default value unified against a type (e.g. \`*true \\| boolean\`). |
 | \`name: key()\` | Bind a field to its map key (so \`feature: log: {}\` gets \`name: 'log'\`). |
 | \`$$path$$\` | Interpolate a model value into a string — e.g. the SDK \`name\`. |
-| \`@"file.aon"\` | Include another fragment (how the index files work). |
+| \`@"./file.aon"\` | Include another fragment (how the index files work). The \`./\` is required on a local path. |
 | \`x: .y\` | Reference another path's value (e.g. \`deps: ts: .js\`). |
 
 For example, the schema for every feature entry:

package/src/sdkgen.ts

@@ -17,7 +17,7 @@ import type {
   ActionResult,
 } from './types'
 
-import { SdkGenError, requirePath, isAuthActive, resolveAuthPrefix, isHttpBasicAuth,
+import { SdkGenError, requirePath, isAuthActive, resolveAuthPrefix, resolveAuthIn, resolveAuthName, isAuthSuppressed, isHttpBasicAuth,
   CONFIG_DATA_THRESHOLD, CONFIG_REPR_VALUES, isConfigData, configRepr,
   configReprSetting, configDefinition, clean, rawStringLiteral } from './utility'
 
@@ -1220,6 +1220,9 @@ export {
   requirePath,
   isAuthActive,
   resolveAuthPrefix,
+  resolveAuthIn,
+  resolveAuthName,
+  isAuthSuppressed,
   isHttpBasicAuth,
   CONFIG_DATA_THRESHOLD,
   CONFIG_REPR_VALUES,

package/src/testkit.ts

@@ -220,8 +220,8 @@ function stageConsumer(opts: StageOptions = {}): Consumer {
   // kind arrives, rather than assuming every index is already wired.
   Fs.writeFileSync(Path.join(sdk, 'model', 'sdk.aon'),
     "name: '" + name + "'\n" +
-    '@"target/target-index.aon"\n' +
-    '@"feature/feature-index.aon"\n' +
+    '@"./target/target-index.aon"\n' +
+    '@"./feature/feature-index.aon"\n' +
     (opts.extra ? opts.extra + '\n' : ''))
 
   // `@voxgig/sdkgen` has to be resolvable FROM THE CONSUMER, because the