@voxgig/sdkgen 4.5.3 → 4.6.0

package/project/.sdk/src/cmp/go/fragment/Main.fragment.go

@@ -35,7 +35,7 @@ func NewProjectNameSDK(options map[string]any) *ProjectNameSDK {
 
 	sdk.options = sdk.utility.MakeOptions(sdk.rootctx)
 
-	if vs.GetPath([]any{"feature", "test", "active"}, sdk.options) == true {
+	if vs.GetPath(sdk.options, []any{"feature", "test", "active"}) == true {
 		sdk.Mode = "test"
 	}
 
@@ -48,7 +48,7 @@ func NewProjectNameSDK(options map[string]any) *ProjectNameSDK {
 	// must be added before them to sit at the base of the chain.
 	featureOpts := ToMapAny(vs.GetProp(sdk.options, "feature"))
 	if featureOpts != nil {
-		if fo, ok := vs.GetPath([]any{"__derived__", "featureorder"}, sdk.options).([]any); ok {
+		if fo, ok := vs.GetPath(sdk.options, []any{"__derived__", "featureorder"}).([]any); ok {
 			for _, n := range fo {
 				fname, _ := n.(string)
 				fopts := ToMapAny(featureOpts[fname])
@@ -188,12 +188,12 @@ func (sdk *ProjectNameSDK) Direct(fetchargs map[string]any) (map[string]any, err
 
 // Is this raw-access op permitted by the SDK's allow.op option?
 func (sdk *ProjectNameSDK) opAllowed(op string) bool {
-	allowOp, _ := vs.GetPath([]any{"allow", "op"}, sdk.options).(string)
+	allowOp, _ := vs.GetPath(sdk.options, []any{"allow", "op"}).(string)
 	return strings.Contains(allowOp, op)
 }
 
 func (sdk *ProjectNameSDK) opDenied(op string) map[string]any {
-	allowOp, _ := vs.GetPath([]any{"allow", "op"}, sdk.options).(string)
+	allowOp, _ := vs.GetPath(sdk.options, []any{"allow", "op"}).(string)
 	return map[string]any{
 		"ok": false,
 		"err": fmt.Errorf("ProjectNameSDK: %s: operation not allowed by"+
@@ -322,7 +322,7 @@ func (sdk *ProjectNameSDK) Graphql(
 	// body, and the raw path represents a non-2xx as ok:false with no err —
 	// so returning early on status would discard the server's own
 	// diagnostics, which are the only useful part of that response.
-	errors, _ := vs.GetPath([]any{"data", "errors"}, res).([]any)
+	errors, _ := vs.GetPath(res, []any{"data", "errors"}).([]any)
 
 	if 0 < len(errors) {
 		msg, _ := vs.GetProp(errors[0], "message").(string)

package/project/.sdk/src/cmp/java/Config_java.ts

@@ -7,6 +7,12 @@ import {
   each,
   isAuthActive,
   resolveAuthPrefix,
+  targetFeatures,
+} from '@voxgig/sdkgen'
+
+
+import {
+  serverVariables,
 } from '@voxgig/sdkgen'
 
 
@@ -37,7 +43,10 @@ const Config = cmp(async function Config(props: any) {
   const javapackage = javaPackage(model)
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 
@@ -71,6 +80,18 @@ const Config = cmp(async function Config(props: any) {
   const options: Record<string, any> = {
     base: baseUrl,
   }
+
+  // Templated server URL: emit the spec's server-variable defaults so the
+  // runtime can substitute {name} placeholders in base (see MakeOptions).
+  // Without this block the placeholder reaches the wire verbatim — java
+  // shipped `http://host/api/{account_id}/element` as a real URL, which is
+  // worse than the construction error every other target raises.
+  const svars = serverVariables(model)
+  if (0 < svars.length) {
+    options.server = svars.reduce(
+      (a: any, v: any) => (a[v.name] = v.dflt, a), {} as Record<string, string>)
+  }
+
   if (authActive) {
     options.auth = { prefix: authPrefix }
   }

package/project/.sdk/src/cmp/java/Main_java.ts

@@ -4,6 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each,
   File, Content, Copy, Folder, Fragment,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -34,7 +35,10 @@ const Main = cmp(async function Main(props: any) {
   const { model } = props.ctx$
 
   const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   // The Java package root for every runtime piece (like GOMODULE for go):
   // e.g. voxgig.solardemosdk -> voxgig.solardemosdk.core etc.

package/project/.sdk/src/cmp/java/ReadmeQuick_java.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityOps } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityOps , serverVariables} from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -32,6 +32,18 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
   const authActive = isAuthActive(model)
 
+  // Server variables (a templated server URL) are REQUIRED at construction
+  // - the SDK throws rather than request a URL with a literal
+  // {account_id} in it - so a quickstart that omits them is a quickstart
+  // that fails on its first line.
+  const svars = serverVariables(model)
+  const javaServerLines = 0 === svars.length ? '' :
+    'Map<String, Object> server = new java.util.LinkedHashMap<>();\n' +
+    svars.map((v: any) =>
+      `server.put("${v.name}", "<${v.name}>");\n`).join('') +
+    'options.put("server", server);\n'
+
+
   // A type-correct Java literal for a param — the loose object model means
   // all values live in a Map<String, Object>.
   const javaLit = (type: any, placeholder: string = 'example'): string => {
@@ -52,7 +64,7 @@ import ${javaPackage(model)}.core.${SDK};
 
 Map<String, Object> options = new java.util.LinkedHashMap<>();
 options.put("apikey", System.getenv("${envName(model)}_APIKEY"));
-${SDK} client = new ${SDK}(options);
+${javaServerLines}${SDK} client = new ${SDK}(options);
 \`\`\`
 
 `)
@@ -63,7 +75,9 @@ ${SDK} client = new ${SDK}(options);
 \`\`\`java
 import ${javaPackage(model)}.core.${SDK};
 
-${SDK} client = new ${SDK}();
+${'' === javaServerLines
+      ? `${SDK} client = new ${SDK}();`
+      : `Map<String, Object> options = new java.util.LinkedHashMap<>();\n${javaServerLines}${SDK} client = new ${SDK}(options);`}
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/java/ReadmeTopQuick_java.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape , serverVariables} from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -35,6 +35,18 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
 
   const authActive = isAuthActive(model)
 
+  // Server variables (a templated server URL) are REQUIRED at construction
+  // - the SDK throws rather than request a URL with a literal
+  // {account_id} in it - so a quickstart that omits them is a quickstart
+  // that fails on its first line.
+  const svars = serverVariables(model)
+  const javaServerLines = 0 === svars.length ? '' :
+    'Map<String, Object> server = new java.util.LinkedHashMap<>();\n' +
+    svars.map((v: any) =>
+      `server.put("${v.name}", "<${v.name}>");\n`).join('') +
+    'options.put("server", server);\n'
+
+
   Content(`\`\`\`java
 import ${javaPackage(model)}.core.${SDK};
 
@@ -43,12 +55,14 @@ import ${javaPackage(model)}.core.${SDK};
   if (authActive) {
     Content(`Map<String, Object> options = new java.util.LinkedHashMap<>();
 options.put("apikey", System.getenv("${envName(model)}_APIKEY"));
-${SDK} client = new ${SDK}(options);
+${javaServerLines}${SDK} client = new ${SDK}(options);
 
 `)
   }
   else {
-    Content(`${SDK} client = new ${SDK}();
+    Content(`${'' === javaServerLines
+      ? `${SDK} client = new ${SDK}();`
+      : `Map<String, Object> options = new java.util.LinkedHashMap<>();\n${javaServerLines}${SDK} client = new ${SDK}(options);`}
 
 `)
   }

package/project/.sdk/src/cmp/java/TestDirect_java.ts

@@ -11,7 +11,9 @@ import {
   File,
   cmp,
   snakify,
-  isAuthActive, envName, envToken
+  isAuthActive,
+  serverVarEnv,
+  serverVariables, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -87,6 +89,20 @@ const TestDirect = cmp(function TestDirect(props: any) {
 
   const authActive = isAuthActive(model)
 
+
+  // A templated server URL (OpenAPI server variables) makes a LIVE client
+  // impossible to construct without values: MakeOptions throws rather than
+  // request a URL with a literal `{account_id}` in it. Taken from the
+  // environment, the same way the apikey is.
+  const svars = serverVariables(model)
+  const serverEnvEntry = svars
+    .map((v: any) => `    envm.put("${serverVarEnv(PROJECTNAME, v.name)}", ${JSON.stringify(v.dflt)});\n`).join('')
+  const serverLiveField = 0 === svars.length ? '' :
+    `      Map<String, Object> serveropt = new LinkedHashMap<>();\n` +
+    svars.map((v: any) =>
+      `      serveropt.put("${v.name}", env.get("${serverVarEnv(PROJECTNAME, v.name)}"));\n`).join('') +
+    `      mergedOpts.put("server", serveropt);\n`
+
   const opnames = Object.keys(entity.op || {})
   const hasLoad = opnames.includes('load')
   const hasList = opnames.includes('list')
@@ -465,7 +481,7 @@ ${loadSkipBlock}    ${SDK} client = setup.client;
     Map<String, Object> envm = new LinkedHashMap<>();
     envm.put("${entidEnvVar}", new LinkedHashMap<>());
     envm.put("${PROJECTNAME}_TEST_LIVE", "FALSE");
-${authActive ? `    envm.put("${PROJECTNAME}_APIKEY", "NONE");\n` : ''}    Map<String, Object> env = RunnerSupport.envOverride(envm);
+${authActive ? `    envm.put("${PROJECTNAME}_APIKEY", "");\n` : ''}${serverEnvEntry}    Map<String, Object> env = RunnerSupport.envOverride(envm);
 
     boolean live = "TRUE".equals(env.get("${PROJECTNAME}_TEST_LIVE"));
 
@@ -473,8 +489,11 @@ ${authActive ? `    envm.put("${PROJECTNAME}_APIKEY", "NONE");\n` : ''}    Map<S
     setup.calls = calls;
 
     if (live) {
-      Map<String, Object> mergedOpts = new LinkedHashMap<>();
-${authActive ? `      mergedOpts.put("apikey", env.get("${PROJECTNAME}_APIKEY"));\n` : ''}      setup.client = new ${SDK}(mergedOpts);
+      // sdk-test-control.json's test.client.options seeds the live
+      // client; the generated fields below overwrite anything they name.
+      Map<String, Object> mergedOpts =
+          new LinkedHashMap<>(RunnerSupport.liveClientOptions());
+${authActive ? `      mergedOpts.put("apikey", env.get("${PROJECTNAME}_APIKEY"));\n` : ''}${serverLiveField}      setup.client = new ${SDK}(mergedOpts);
       setup.live = true;
 
       Map<String, Object> idmap = new LinkedHashMap<>();

package/project/.sdk/src/cmp/java/TestEntity_java.ts

@@ -17,7 +17,9 @@ import {
   each,
   buildIdNames,
   getMatchEntries,
-  isAuthActive, envName, envToken
+  isAuthActive,
+  serverVarEnv,
+  serverVariables, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -67,6 +69,20 @@ const TestEntity = cmp(function TestEntity(props: any) {
 
   const authActive = isAuthActive(model)
 
+
+  // A templated server URL (OpenAPI server variables) makes a LIVE client
+  // impossible to construct without values: MakeOptions throws rather than
+  // request a URL with a literal `{account_id}` in it. Taken from the
+  // environment, the same way the apikey is.
+  const svars = serverVariables(model)
+  const serverEnvEntry = svars
+    .map((v: any) => `    envm.put("${serverVarEnv(PROJUPPER, v.name)}", ${JSON.stringify(v.dflt)});\n`).join('')
+  const serverLiveField = 0 === svars.length ? '' :
+    `      Map<String, Object> serveropt = new LinkedHashMap<>();\n` +
+    svars.map((v: any) =>
+      `      serveropt.put("${v.name}", env.get("${serverVarEnv(PROJUPPER, v.name)}"));\n`).join('') +
+    `      liveOpts.put("server", serveropt);\n`
+
   const idnames = buildIdNames(entity, basicflow)
 
   // Get all update data entries for alias generation
@@ -256,7 +272,7 @@ ${allSteps.length > 0 ? `    ${SDK} client = setup.client;\n\n` : ''}`)
     envm.put("${entidEnvVar}", idmap);
     envm.put("${PROJUPPER}_TEST_LIVE", "FALSE");
     envm.put("${PROJUPPER}_TEST_EXPLAIN", "FALSE");
-${authActive ? `    envm.put("${PROJUPPER}_APIKEY", "NONE");\n` : ''}    Map<String, Object> env = RunnerSupport.envOverride(envm);
+${authActive ? `    envm.put("${PROJUPPER}_APIKEY", "");\n` : ''}${serverEnvEntry}    Map<String, Object> env = RunnerSupport.envOverride(envm);
 
     Map<String, Object> idmapResolved = Helpers.toMapAny(env.get("${entidEnvVar}"));
     if (idmapResolved == null) {
@@ -276,8 +292,17 @@ ${authActive ? `    envm.put("${PROJUPPER}_APIKEY", "NONE");\n` : ''}    Map<Str
     Content(`
     boolean live = "TRUE".equals(env.get("${PROJUPPER}_TEST_LIVE"));
     if (live) {
-      Map<String, Object> liveOpts = new LinkedHashMap<>();
-${authActive ? `      liveOpts.put("apikey", env.get("${PROJUPPER}_APIKEY"));\n` : ''}      Object mergedOpts = Struct.merge(Struct.jt(liveOpts, extra));
+      // sdk-test-control.json's test.client.options seeds the live
+      // client; the generated fields below overwrite anything they name.
+      Map<String, Object> liveOpts =
+          new LinkedHashMap<>(RunnerSupport.liveClientOptions());
+${authActive ? `      liveOpts.put("apikey", env.get("${PROJUPPER}_APIKEY"));\n` : ''}${serverLiveField}      // An empty map, not a null one: merge answers null when its last
+      // entry is null, and basicSetup is normally called with no extras -
+      // so a bare null silently discarded the apikey and server values
+      // above.
+      Map<String, Object> extraOpts =
+          extra == null ? new LinkedHashMap<>() : extra;
+      Object mergedOpts = Struct.merge(Struct.jt(liveOpts, extraOpts));
       client = new ${SDK}(Helpers.toMapAny(mergedOpts));
     }
 

package/project/.sdk/src/cmp/js/Config_js.ts

@@ -17,6 +17,7 @@ import {
   isConfigData,
   resolveAuthPrefix,
   serverVariables,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -40,7 +41,10 @@ const Config = cmp(async function Config(props: any) {
   const model: Model = ctx$.model
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   const ff = Path.normalize(__dirname + '/../../../src/cmp/js/fragment/')
 

package/project/.sdk/src/cmp/js/Main_js.ts

@@ -5,6 +5,7 @@ import {
   cmp, each, names, cmap,
   List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
   entityClassName, entityCollection, srcFeatureExcludes, stationLibrary,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -35,7 +36,10 @@ const Main = cmp(async function Main(props: any) {
   const { model } = props.ctx$
 
   const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   Package({ target })
 

package/project/.sdk/src/cmp/js/Package_js.ts

@@ -13,6 +13,7 @@ import {
   PUBLISHER_URL,
   packageVersion,
   authorInfo,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -36,7 +37,9 @@ const Package = cmp(async function Package(props: any) {
   // constant here did.
   const author = authorInfo(model, target.name)
 
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by applicability: a feature that does not apply to this
+  // target must not inject its deps into the generated manifest.
+  const feature = targetFeatures(model, target)
 
   const only = (kind: string, deps: any) =>
     omap(deps, ([k, v]: any) => [v.active && kind === v.kind ? k : undefined, v.version])

package/project/.sdk/src/cmp/kotlin/Config_kotlin.ts

@@ -7,6 +7,7 @@ import {
   each,
   isAuthActive,
   resolveAuthPrefix,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -36,7 +37,10 @@ const Config = cmp(async function Config(props: any) {
   const kotlinpackage = kotlinPackage(model)
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 

package/project/.sdk/src/cmp/lean/Config_lean.ts

@@ -5,6 +5,7 @@ import {
   each,
   isAuthActive,
   resolveAuthPrefix,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 import {
@@ -29,7 +30,10 @@ const Config = cmp(async function Config(props: any) {
   const model: Model = ctx$.model
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 
   const authActive = isAuthActive(model)

package/project/.sdk/src/cmp/lua/Config_lua.ts

@@ -15,6 +15,7 @@ import {
   isConfigData,
   resolveAuthPrefix,
   serverVariables,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -40,7 +41,10 @@ const Config = cmp(async function Config(props: any) {
   const model: Model = ctx$.model
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 

package/project/.sdk/src/cmp/lua/Main_lua.ts

@@ -4,6 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each, names, cmap,
   List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -31,7 +32,10 @@ const Main = cmp(async function Main(props: any) {
   const { model } = props.ctx$
 
   const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   Package({ target })
 

package/project/.sdk/src/cmp/lua/Package_lua.ts

@@ -9,6 +9,7 @@ import {
   keywords,
   repoInfo, packageName,
   packageVersion,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -78,7 +79,9 @@ dependencies = {
     // factory falls back to. The station feature additionally carries the
     // VENDORED voxgig_station library beside its adapter (no voxgig-station
     // rock exists to depend on - station design 9.2's registry-less tier).
-    const feature = getModelPath(model, `main.${KIT}.feature`)
+    // Gated: a feature that does not apply to lua must not be listed
+    // as a rockspec module — the require would not resolve.
+    const feature = targetFeatures(model, target)
     let featureModules = `    ["feature.base_feature"] = "feature/base_feature.lua",\n`
     each(feature, (f: any) => {
       featureModules +=

package/project/.sdk/src/cmp/ocaml/Config_ocaml.ts

@@ -9,6 +9,7 @@ import {
   isAuthActive,
   isConfigData,
   resolveAuthPrefix,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -34,7 +35,10 @@ const Config = cmp(async function Config(props: any) {
 
   const model: Model = ctx$.model
 
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   // The canonical config OBJECT and its JSON, from the shared helper. Both
   // representations render from the same `def`, so they cannot describe

package/project/.sdk/src/cmp/perl/Main_perl.ts

@@ -4,6 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each, names,
   File, Content, Copy, Folder, Fragment,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -36,7 +37,10 @@ const Main = cmp(async function Main(props: any) {
   const { model } = props.ctx$
 
   const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   Package({ target })
 

package/project/.sdk/src/cmp/php/Config_php.ts

@@ -16,6 +16,7 @@ import {
   rawStringLiteral,
   resolveAuthPrefix,
   serverVariables,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -40,7 +41,10 @@ const Config = cmp(async function Config(props: any) {
   const model: Model = ctx$.model
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 

package/project/.sdk/src/cmp/php/Main_php.ts

@@ -4,6 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each, names, cmap,
   List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -31,7 +32,10 @@ const Main = cmp(async function Main(props: any) {
   const { model } = props.ctx$
 
   const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   Package({ target })
 

package/project/.sdk/src/cmp/py/Config_py.ts

@@ -15,6 +15,7 @@ import {
   isConfigData,
   resolveAuthPrefix,
   serverVariables,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -39,7 +40,10 @@ const Config = cmp(async function Config(props: any) {
   const model: Model = ctx$.model
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 

package/project/.sdk/src/cmp/py/Main_py.ts

@@ -5,6 +5,7 @@ import {
   cmp, each, names, cmap,
   List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
   entityClassName, entityCollection,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -32,7 +33,10 @@ const Main = cmp(async function Main(props: any) {
   const { model } = props.ctx$
 
   const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   // The one package directory everything the SDK owns lives in.
   const pkgdir = model.const.Name.toLowerCase() + '_sdk'

package/project/.sdk/src/cmp/py/ReadmeQuick_py.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName, matchArg, idLiteral } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName, matchArg, idLiteral , serverVariables} from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -38,10 +38,23 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   ) as any
 
   const authActive = isAuthActive(model)
+
+  // Server variables (a templated server URL) are REQUIRED at construction
+  // - the SDK refuses rather than request a URL with a literal
+  // {account_id} in it - so a quickstart that omits them is a quickstart
+  // that fails on its first line.
+  const svars = serverVariables(model)
+  const pyServerField = 0 === svars.length ? '' :
+    `\n    "server": {` +
+    svars.map((v: any) => `\n        "${v.name}": "<${v.name}>",`).join('') +
+    `\n    },`
+
   const apikeyImport = authActive ? `import os\n` : ''
   const ctor = authActive
-    ? `${model.const.Name}SDK({\n    "apikey": os.environ.get("${envName(model)}_APIKEY"),\n})`
-    : `${model.const.Name}SDK()`
+    ? `${model.const.Name}SDK({\n    "apikey": os.environ.get("${envName(model)}_APIKEY"),${pyServerField}\n})`
+    : ('' === pyServerField
+      ? `${model.const.Name}SDK()`
+      : `${model.const.Name}SDK({${pyServerField}\n})`)
 
   Content(`### 1. Create a client