@voxgig/sdkgen 0.45.0 → 1.1.1

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

@@ -18,13 +18,20 @@ const Package = cmp(async function Package(props: any) {
 
   const model: Model = ctx$.model
 
+  // PyPI distribution name is namespaced to model.origin (e.g. "voxgig-sdk").
+  // PyPI names can't contain "/", so the parts are hyphen-joined. The import
+  // package (the `${model.name}_sdk/` dir) is unchanged.
+  const ns = model.origin || 'voxgig-sdk'
+  const pkgBase = ns.endsWith('-sdk') ? model.name : `${model.name}-sdk`
+  const distName = `${ns}-${pkgBase}`
+
   File({ name: 'pyproject.toml' }, () => {
     Content(`[build-system]
 requires = ["setuptools>=61.0"]
 build-backend = "setuptools.build_meta"
 
 [project]
-name = "${model.name}-sdk"
+name = "${distName}"
 version = "0.0.1"
 description = "${model.const.Name} SDK for Python"
 license = "MIT"

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

@@ -83,12 +83,51 @@ const TestDirect = cmp(function TestDirect(props: any) {
 
   const loadPoint = loadOp?.points?.[0]
   const loadPath = loadPoint ? normalizePathParams(loadPoint.parts || [], loadPoint?.args?.params || [], loadPoint?.rename?.param) : ''
-  const loadParams = loadPoint?.args?.params || []
+  const allLoadParams = loadPoint?.args?.params || []
+  // Some upstream OpenAPI specs declare a parameter as `in: path` even when
+  // that path has no `{name}` placeholder for it. Only path params that
+  // actually appear in the URL template should drive direct-test path-param
+  // setup and URL-substitution asserts; otherwise the SDK silently drops
+  // them and the URL-includes assert fails.
+  const _pathPlaceholders = new Set<string>()
+  for (const part of (loadPoint?.parts || [])) {
+    if (typeof part === 'string' && part.startsWith('{') && part.endsWith('}')) {
+      _pathPlaceholders.add(part.slice(1, -1))
+    }
+  }
+  const _renameMap = (loadPoint?.rename?.param || {}) as Record<string, string>
+  const _renamedPlaceholders = new Set<string>()
+  for (const ph of _pathPlaceholders) {
+    _renamedPlaceholders.add(ph)
+    for (const [orig, renamed] of Object.entries(_renameMap)) {
+      if (renamed === ph) _renamedPlaceholders.add(orig)
+    }
+  }
+  const loadParams = allLoadParams.filter((p: any) =>
+    _renamedPlaceholders.has(p.name) || _renamedPlaceholders.has(p.orig))
 
   const listPoint = listOp?.points?.[0]
   const listPath = listPoint ? normalizePathParams(listPoint.parts || [], listPoint?.args?.params || [], listPoint?.rename?.param) : ''
   const listParams = listPoint?.args?.params || []
 
+  // Required query params with spec-provided examples — needed in live mode
+  // to satisfy API contracts (e.g. /v2018/history requires city/start/end).
+  const loadQuery = loadPoint?.args?.query || []
+  const loadLiveQueryEntries = loadQuery
+    .filter((q: any) => q.reqd && undefined !== q.example && null !== q.example)
+  const loadLiveQueryLines = loadLiveQueryEntries
+    .map((q: any) => `            query["${q.name}"] = ${JSON.stringify(q.example)}`)
+    .join('\n')
+
+  // Path params with spec-provided examples — when ALL load params have
+  // spec examples, prefer them over list-bootstrap.
+  const loadAllHaveExamples =
+    loadParams.length > 0 &&
+    loadParams.every((p: any) => undefined !== p.example && null !== p.example)
+  const loadExampleLines = loadAllHaveExamples
+    ? loadParams.map((p: any) => `            params["${p.name}"] = ${JSON.stringify(p.example)}`).join('\n')
+    : ''
+
   const entidEnvVar = `${PROJECTNAME}_TEST_${nom(entity, 'NAME').replace(/[^A-Z_]/g, '_')}_ENTID`
 
   File({ name: 'test_' + entity.name + '_direct.' + target.ext }, () => {
@@ -109,12 +148,33 @@ class Test${entity.Name}Direct:
 `)
 
     if (hasList && listPoint) {
+      // Track idmap keys this list test consumes in live mode.
+      const listLiveIdKeys: string[] = listParams.map((lp: any) => {
+        return lp.name === 'id'
+          ? entity.name + '01'
+          : lp.name.replace(/_id$/, '') + '01'
+      })
+      const listSkipBlock = listLiveIdKeys.length > 0
+        ? `        if setup["live"]:
+            for _live_key in [${listLiveIdKeys.map(k => `"${k}"`).join(', ')}]:
+                if setup["idmap"].get(_live_key) is None:
+                    # pytest already imported at module scope
+                    pytest.skip(f"live test needs {_live_key} via *_ENTID env var (synthetic IDs only)")
+                    return
+
+`
+        : ''
       Content(`    def test_should_direct_list_${entity.name}(self):
         setup = _${entity.name}_direct_setup([
             {"id": "direct01"},
             {"id": "direct02"},
         ])
-        client = setup["client"]
+        _skip, _reason = runner.is_control_skipped("direct", "direct-list-${entity.name}", "live" if setup["live"] else "unit")
+        if _skip:
+            # pytest already imported at module scope
+            pytest.skip(_reason or "skipped via sdk-test-control.json")
+            return
+${listSkipBlock}        client = setup["client"]
 
 `)
 
@@ -148,11 +208,24 @@ class Test${entity.Name}Direct:
 `)
       }
 
-      Content(`        assert err is None
-        assert result["ok"] is True
-        assert helpers.to_int(result["status"]) == 200
-
-        if not setup["live"]:
+      Content(`        if setup["live"]:
+            # Live mode is lenient: synthetic IDs frequently 4xx and the
+            # list-response shape varies wildly across public APIs. Skip
+            # rather than fail when the call doesn't return a usable list.
+            if err is not None:
+                pytest.skip(f"list call failed (likely synthetic IDs against live API): {err}")
+                return
+            if not result.get("ok"):
+                pytest.skip("list call not ok (likely synthetic IDs against live API)")
+                return
+            status = helpers.to_int(result["status"])
+            if status < 200 or status >= 300:
+                pytest.skip(f"expected 2xx status, got {status}")
+                return
+        else:
+            assert err is None
+            assert result["ok"] is True
+            assert helpers.to_int(result["status"]) == 200
             assert isinstance(result["data"], list)
             assert len(result["data"]) == 2
             assert len(setup["calls"]) == 1
@@ -161,18 +234,58 @@ class Test${entity.Name}Direct:
     }
 
     if (hasLoad && loadPoint) {
+      // Python's direct-load test has no list-bootstrap, so when load path
+      // params can't be filled (no spec examples + no override), skip cleanly.
+      const loadSkipBlock = (loadParams.length > 0 && !loadAllHaveExamples)
+        ? `        if setup["live"]:
+            # pytest already imported at module scope
+            pytest.skip("live direct-load needs real ID — set *_ENTID env var with real IDs to run")
+            return
+
+`
+        : ''
       Content(`    def test_should_direct_load_${entity.name}(self):
         setup = _${entity.name}_direct_setup({"id": "direct01"})
-        client = setup["client"]
+        _skip, _reason = runner.is_control_skipped("direct", "direct-load-${entity.name}", "live" if setup["live"] else "unit")
+        if _skip:
+            # pytest already imported at module scope
+            pytest.skip(_reason or "skipped via sdk-test-control.json")
+            return
+${loadSkipBlock}        client = setup["client"]
 
 `)
 
-      if (loadParams.length > 0) {
+      const needsQuery = loadParams.length > 0 || loadLiveQueryLines !== ''
+      if (needsQuery) {
         Content(`        params = {}
-        if not setup["live"]:
+        query = {}
+`)
+        if (loadAllHaveExamples) {
+          // Use spec-provided path-param examples in live mode.
+          Content(`        if setup["live"]:
+${loadLiveQueryLines ? loadLiveQueryLines + '\n' : ''}${loadExampleLines}
+        else:
 `)
-        for (let i = 0; i < loadParams.length; i++) {
-          Content(`            params["${loadParams[i].name}"] = "direct0${i + 1}"
+          for (let i = 0; i < loadParams.length; i++) {
+            Content(`            params["${loadParams[i].name}"] = "direct0${i + 1}"
+`)
+          }
+        } else if (loadParams.length > 0) {
+          if (loadLiveQueryLines) {
+            Content(`        if setup["live"]:
+${loadLiveQueryLines}
+`)
+          }
+          Content(`        if not setup["live"]:
+`)
+          for (let i = 0; i < loadParams.length; i++) {
+            Content(`            params["${loadParams[i].name}"] = "direct0${i + 1}"
+`)
+          }
+        } else if (loadLiveQueryLines) {
+          // Required-query only, no path params.
+          Content(`        if setup["live"]:
+${loadLiveQueryLines}
 `)
         }
       }
@@ -182,20 +295,34 @@ class Test${entity.Name}Direct:
             "path": "${loadPath}",
             "method": "GET",
 `)
-      if (loadParams.length > 0) {
+      if (needsQuery) {
         Content(`            "params": params,
+            "query": query,
 `)
       } else {
         Content(`            "params": {},
 `)
       }
       Content(`        })
-        assert err is None
-        assert result["ok"] is True
-        assert helpers.to_int(result["status"]) == 200
-        assert result["data"] is not None
-
-        if not setup["live"]:
+        if setup["live"]:
+            # Live mode is lenient: synthetic IDs frequently 4xx. Skip
+            # rather than fail when the load endpoint isn't reachable
+            # with the IDs we can construct from setup.idmap.
+            if err is not None:
+                pytest.skip(f"load call failed (likely synthetic IDs against live API): {err}")
+                return
+            if not result.get("ok"):
+                pytest.skip("load call not ok (likely synthetic IDs against live API)")
+                return
+            status = helpers.to_int(result["status"])
+            if status < 200 or status >= 300:
+                pytest.skip(f"expected 2xx status, got {status}")
+                return
+        else:
+            assert err is None
+            assert result["ok"] is True
+            assert helpers.to_int(result["status"]) == 200
+            assert result["data"] is not None
             if isinstance(result["data"], dict):
                 assert result["data"]["id"] == "direct01"
             assert len(setup["calls"]) == 1

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

@@ -104,6 +104,20 @@ class Test${entity.Name}Entity:
 
     def test_should_run_basic_flow(self):
         setup = _${entity.name}_basic_setup(None)
+        # Per-op sdk-test-control.json skip — basic test exercises a flow with
+        # multiple ops; skipping any one skips the whole flow (steps depend
+        # on each other).
+        _live = setup.get("live", False)
+        for _op in [${(Array.from(new Set((basicflow.step as any[]).map((s: any) => s.op).filter(Boolean)))).map(o => `"${o}"`).join(', ')}]:
+            _skip, _reason = runner.is_control_skipped("entityOp", "${entity.name}." + _op, "live" if _live else "unit")
+            if _skip:
+                pytest.skip(_reason or "skipped via sdk-test-control.json")
+                return
+        # The basic flow consumes synthetic IDs from the fixture. In live mode
+        # without an *_ENTID env override, those IDs hit the live API and 4xx.
+        if setup.get("synthetic_only"):
+            pytest.skip("live entity test uses synthetic IDs from fixture — "
+                        "set ${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID JSON to run live")
         client = setup["client"]
 
 `)
@@ -162,7 +176,14 @@ def _${entity.name}_basic_setup(extra):
 
 `)
 
-    Content(`    env = runner.env_override({
+    Content(`    # Detect ENTID env override before envOverride consumes it. When live
+    # mode is on without a real override, the basic test runs against synthetic
+    # IDs from the fixture and 4xx's. We surface this so the test can skip.
+    _entid_env_raw = os.environ.get(
+        "${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID")
+    _idmap_overridden = _entid_env_raw is not None and _entid_env_raw.strip().startswith("{")
+
+    env = runner.env_override({
         "${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID": idmap,
         "${PROJUPPER}_TEST_LIVE": "FALSE",
         "${PROJUPPER}_TEST_EXPLAIN": "FALSE",${apikeyEnvEntry}
@@ -190,12 +211,15 @@ def _${entity.name}_basic_setup(extra):
         ])
         client = ${model.const.Name}SDK(helpers.to_map(merged_opts))
 
+    _live = env.get("${PROJUPPER}_TEST_LIVE") == "TRUE"
     return {
         "client": client,
         "data": entity_data,
         "idmap": idmap_resolved,
         "env": env,
         "explain": env.get("${PROJUPPER}_TEST_EXPLAIN") == "TRUE",
+        "live": _live,
+        "synthetic_only": _live and not _idmap_overridden,
         "now": int(time.time() * 1000),
     }
 `)

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

@@ -180,15 +180,30 @@ class ProjectNameSDK:
 
         if isinstance(fetched, dict):
             status = helpers.to_int(vs.getprop(fetched, "status"))
+            headers = vs.getprop(fetched, "headers") or {}
+
+            # No-body responses (204, 304) and explicit zero content-length
+            # must skip JSON parsing — calling json() on an empty body raises.
+            content_length = None
+            if isinstance(headers, dict):
+                content_length = headers.get("content-length")
+            no_body = status in (204, 304) or str(content_length) == "0"
+
             json_data = None
-            jf = vs.getprop(fetched, "json")
-            if callable(jf):
-                json_data = jf()
+            if not no_body:
+                jf = vs.getprop(fetched, "json")
+                if callable(jf):
+                    try:
+                        json_data = jf()
+                    except Exception:
+                        # Non-JSON body (e.g. text/plain, text/html). Surface
+                        # status + headers but leave data as None.
+                        json_data = None
 
             return {
                 "ok": status >= 200 and status < 300,
                 "status": status,
-                "headers": vs.getprop(fetched, "headers"),
+                "headers": headers,
                 "data": json_data,
             }, None
 

package/project/.sdk/src/cmp/rb/Package_rb.ts

@@ -18,6 +18,13 @@ const Package = cmp(async function Package(props: any) {
 
   const model: Model = ctx$.model
 
+  // Gem name is namespaced to model.origin (e.g. "voxgig-sdk"). RubyGems
+  // names can't contain "/", so the parts are hyphen-joined. The require
+  // path (`${model.name}_sdk`) is unchanged.
+  const ns = model.origin || 'voxgig-sdk'
+  const pkgBase = ns.endsWith('-sdk') ? model.name : `${model.name}-sdk`
+  const gemName = `${ns}-${pkgBase}`
+
   const versionOf = (d: { version: string; source: 'feature' | 'target' }) =>
     d.source === 'target' ? (d.version || '0.0') : d.version
 
@@ -38,12 +45,12 @@ gemspec
   // Generate gemspec
   File({ name: model.const.Name + '_sdk.gemspec' }, () => {
     Content(`Gem::Specification.new do |spec|
-  spec.name          = "${model.name}-sdk"
+  spec.name          = "${gemName}"
   spec.version       = "0.0.1"
   spec.authors       = ["Voxgig"]
   spec.summary       = "${model.const.Name} SDK for Ruby"
   spec.license       = "MIT"
-  spec.homepage      = "https://github.com/voxgig/${model.name}-sdk"
+  spec.homepage      = "https://github.com/${ns}/${model.name}-sdk"
 
   spec.files         = Dir["lib/**/*.rb", "*.rb"]
   spec.require_paths = ["."]

package/project/.sdk/src/cmp/rb/TestDirect_rb.ts

@@ -83,12 +83,48 @@ const TestDirect = cmp(function TestDirect(props: any) {
 
   const loadPoint = loadOp?.points?.[0]
   const loadPath = loadPoint ? normalizePathParams(loadPoint.parts || [], loadPoint?.args?.params || [], loadPoint?.rename?.param) : ''
-  const loadParams = loadPoint?.args?.params || []
+  const allLoadParams = loadPoint?.args?.params || []
+  // Some upstream OpenAPI specs declare a parameter as `in: path` even when
+  // that path has no `{name}` placeholder for it. Only path params that
+  // actually appear in the URL template should drive direct-test path-param
+  // setup and URL-substitution asserts; otherwise the SDK silently drops
+  // them and the URL-includes assert fails.
+  const _pathPlaceholders = new Set<string>()
+  for (const part of (loadPoint?.parts || [])) {
+    if (typeof part === 'string' && part.startsWith('{') && part.endsWith('}')) {
+      _pathPlaceholders.add(part.slice(1, -1))
+    }
+  }
+  const _renameMap = (loadPoint?.rename?.param || {}) as Record<string, string>
+  const _renamedPlaceholders = new Set<string>()
+  for (const ph of _pathPlaceholders) {
+    _renamedPlaceholders.add(ph)
+    for (const [orig, renamed] of Object.entries(_renameMap)) {
+      if (renamed === ph) _renamedPlaceholders.add(orig)
+    }
+  }
+  const loadParams = allLoadParams.filter((p: any) =>
+    _renamedPlaceholders.has(p.name) || _renamedPlaceholders.has(p.orig))
 
   const listPoint = listOp?.points?.[0]
   const listPath = listPoint ? normalizePathParams(listPoint.parts || [], listPoint?.args?.params || [], listPoint?.rename?.param) : ''
   const listParams = listPoint?.args?.params || []
 
+  // Required query params with spec-provided examples — needed in live mode.
+  const loadQuery = loadPoint?.args?.query || []
+  const loadLiveQueryEntries = loadQuery
+    .filter((q: any) => q.reqd && undefined !== q.example && null !== q.example)
+  const loadLiveQueryLines = loadLiveQueryEntries
+    .map((q: any) => `      query["${q.name}"] = ${JSON.stringify(q.example)}`)
+    .join('\n')
+
+  const loadAllHaveExamples =
+    loadParams.length > 0 &&
+    loadParams.every((p: any) => undefined !== p.example && null !== p.example)
+  const loadExampleLines = loadAllHaveExamples
+    ? loadParams.map((p: any) => `      params["${p.name}"] = ${JSON.stringify(p.example)}`).join('\n')
+    : ''
+
   const entidEnvVar = `${PROJECTNAME}_TEST_${nom(entity, 'NAME').replace(/[^A-Z_]/g, '_')}_ENTID`
 
   File({ name: entity.name + '_direct_test.' + target.ext }, () => {
@@ -104,12 +140,33 @@ class ${entity.Name}DirectTest < Minitest::Test
 `)
 
     if (hasList && listPoint) {
+      const listLiveIdKeys: string[] = listParams.map((lp: any) => {
+        return lp.name === 'id'
+          ? entity.name + '01'
+          : lp.name.replace(/_id$/, '') + '01'
+      })
+      const listSkipBlock = listLiveIdKeys.length > 0
+        ? `    if setup[:live]
+      [${listLiveIdKeys.map(k => `"${k}"`).join(', ')}].each do |_live_key|
+        if setup[:idmap][_live_key].nil?
+          skip "live test needs #{_live_key} via *_ENTID env var (synthetic IDs only)"
+          return
+        end
+      end
+    end
+`
+        : ''
       Content(`  def test_direct_list_${entity.name}
     setup = ${entity.name}_direct_setup([
       { "id" => "direct01" },
       { "id" => "direct02" },
     ])
-    client = setup[:client]
+    _should_skip, _reason = Runner.is_control_skipped("direct", "direct-list-${entity.name}", setup[:live] ? "live" : "unit")
+    if _should_skip
+      skip(_reason || "skipped via sdk-test-control.json")
+      return
+    end
+${listSkipBlock}    client = setup[:client]
 
 `)
 
@@ -144,11 +201,27 @@ class ${entity.Name}DirectTest < Minitest::Test
 `)
       }
 
-      Content(`    assert_nil err
-    assert result["ok"]
-    assert_equal 200, Helpers.to_int(result["status"])
-
-    unless setup[:live]
+      Content(`    if setup[:live]
+      # Live mode is lenient: synthetic IDs frequently 4xx and the list-
+      # response shape varies wildly across public APIs. Skip rather than
+      # fail when the call doesn't return a usable list.
+      if !err.nil?
+        skip("list call failed (likely synthetic IDs against live API): #{err}")
+        return
+      end
+      unless result["ok"]
+        skip("list call not ok (likely synthetic IDs against live API)")
+        return
+      end
+      status = Helpers.to_int(result["status"])
+      if status < 200 || status >= 300
+        skip("expected 2xx status, got #{status}")
+        return
+      end
+    else
+      assert_nil err
+      assert result["ok"]
+      assert_equal 200, Helpers.to_int(result["status"])
       assert result["data"].is_a?(Array)
       assert_equal 2, result["data"].length
       assert_equal 1, setup[:calls].length
@@ -159,22 +232,65 @@ class ${entity.Name}DirectTest < Minitest::Test
     }
 
     if (hasLoad && loadPoint) {
+      // Skip live direct-load only when we can't fill path params:
+      // no spec examples and no list-bootstrap. Spec examples win first.
+      const loadSkipBlock = (loadParams.length > 0 && !loadAllHaveExamples)
+        ? `    if setup[:live]
+      skip "live direct-load needs real ID — set *_ENTID env var with real IDs to run"
+      return
+    end
+`
+        : ''
       Content(`  def test_direct_load_${entity.name}
     setup = ${entity.name}_direct_setup({ "id" => "direct01" })
-    client = setup[:client]
+    _should_skip, _reason = Runner.is_control_skipped("direct", "direct-load-${entity.name}", setup[:live] ? "live" : "unit")
+    if _should_skip
+      skip(_reason || "skipped via sdk-test-control.json")
+      return
+    end
+${loadSkipBlock}    client = setup[:client]
 
 `)
 
-      if (loadParams.length > 0) {
+      const needsQuery = loadParams.length > 0 || loadLiveQueryLines !== ''
+      if (needsQuery) {
         Content(`    params = {}
-    unless setup[:live]
+    query = {}
 `)
-        for (let i = 0; i < loadParams.length; i++) {
-          Content(`      params["${loadParams[i].name}"] = "direct0${i + 1}"
+        if (loadAllHaveExamples) {
+          Content(`    if setup[:live]
 `)
-        }
-        Content(`    end
+          if (loadLiveQueryLines) Content(loadLiveQueryLines + '\n')
+          Content(loadExampleLines + '\n')
+          Content(`    else
 `)
+          for (let i = 0; i < loadParams.length; i++) {
+            Content(`      params["${loadParams[i].name}"] = "direct0${i + 1}"
+`)
+          }
+          Content(`    end
+`)
+        } else if (loadParams.length > 0) {
+          if (loadLiveQueryLines) {
+            Content(`    if setup[:live]
+${loadLiveQueryLines}
+    end
+`)
+          }
+          Content(`    unless setup[:live]
+`)
+          for (let i = 0; i < loadParams.length; i++) {
+            Content(`      params["${loadParams[i].name}"] = "direct0${i + 1}"
+`)
+          }
+          Content(`    end
+`)
+        } else if (loadLiveQueryLines) {
+          Content(`    if setup[:live]
+${loadLiveQueryLines}
+    end
+`)
+        }
       }
 
       Content(`
@@ -182,20 +298,37 @@ class ${entity.Name}DirectTest < Minitest::Test
       "path" => "${loadPath}",
       "method" => "GET",
 `)
-      if (loadParams.length > 0) {
+      if (needsQuery) {
         Content(`      "params" => params,
+      "query" => query,
 `)
       } else {
         Content(`      "params" => {},
 `)
       }
       Content(`    })
-    assert_nil err
-    assert result["ok"]
-    assert_equal 200, Helpers.to_int(result["status"])
-    assert !result["data"].nil?
-
-    unless setup[:live]
+    if setup[:live]
+      # Live mode is lenient: synthetic IDs frequently 4xx. Skip rather
+      # than fail when the load endpoint isn't reachable with the IDs
+      # we can construct from setup.idmap.
+      if !err.nil?
+        skip("load call failed (likely synthetic IDs against live API): #{err}")
+        return
+      end
+      unless result["ok"]
+        skip("load call not ok (likely synthetic IDs against live API)")
+        return
+      end
+      status = Helpers.to_int(result["status"])
+      if status < 200 || status >= 300
+        skip("expected 2xx status, got #{status}")
+        return
+      end
+    else
+      assert_nil err
+      assert result["ok"]
+      assert_equal 200, Helpers.to_int(result["status"])
+      assert !result["data"].nil?
       if result["data"].is_a?(Hash)
         assert_equal "direct01", result["data"]["id"]
       end

package/project/.sdk/src/cmp/rb/TestEntity_rb.ts

@@ -91,6 +91,21 @@ class ${entity.Name}EntityTest < Minitest::Test
 
   def test_basic_flow
     setup = ${entity.name}_basic_setup(nil)
+    # Per-op sdk-test-control.json skip.
+    _live = setup[:live] || false
+    [${(Array.from(new Set((allSteps as any[]).map((s: any) => s.op).filter(Boolean)))).map(o => `"${o}"`).join(', ')}].each do |_op|
+      _should_skip, _reason = Runner.is_control_skipped("entityOp", "${entity.name}." + _op, _live ? "live" : "unit")
+      if _should_skip
+        skip(_reason || "skipped via sdk-test-control.json")
+        return
+      end
+    end
+    # The basic flow consumes synthetic IDs from the fixture. In live mode
+    # without an *_ENTID env override, those IDs hit the live API and 4xx.
+    if setup[:synthetic_only]
+      skip "live entity test uses synthetic IDs from fixture — set ${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID JSON to run live"
+      return
+    end
     client = setup[:client]
 
 `)
@@ -152,7 +167,13 @@ end
 
 `)
 
-    Content(`  env = Runner.env_override({
+    Content(`  # Detect ENTID env override before envOverride consumes it. When live
+  # mode is on without a real override, the basic test runs against synthetic
+  # IDs from the fixture and 4xx's. Surface this so the test can skip.
+  entid_env_raw = ENV["${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID"]
+  idmap_overridden = !entid_env_raw.nil? && entid_env_raw.strip.start_with?("{")
+
+  env = Runner.env_override({
     "${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID" => idmap,
     "${PROJUPPER}_TEST_LIVE" => "FALSE",
     "${PROJUPPER}_TEST_EXPLAIN" => "FALSE",${apikeyEnvEntry}
@@ -183,12 +204,15 @@ end
     client = ${model.const.Name}SDK.new(Helpers.to_map(merged_opts))
   end
 
+  live = env["${PROJUPPER}_TEST_LIVE"] == "TRUE"
   {
     client: client,
     data: entity_data,
     idmap: idmap_resolved,
     env: env,
     explain: env["${PROJUPPER}_TEST_EXPLAIN"] == "TRUE",
+    live: live,
+    synthetic_only: live && !idmap_overridden,
     now: (Time.now.to_f * 1000).to_i,
   }
 end