@voxgig/sdkgen 4.15.0 → 4.17.0

package/model/sdkgen.aon

@@ -28,21 +28,10 @@ main: kit: config: repr: *'auto' | 'literal' | 'data'
 main: kit: test: {
 
   live: {
-    # Whether a live run ASSERTS or merely observes.
-    #
-    # false (the default, and the right answer for a fleet SDK generated
-    # against an arbitrary third-party API): a non-2xx in live mode is an
-    # early return, not a failure. Synthetic IDs 4xx constantly and list
-    # response shapes vary wildly, so asserting would mean permanent red.
-    #
-    # true: live assertions match the offline ones — a non-2xx FAILS, and a
-    # missing idmap entry fails rather than skipping. Set this when the
-    # project OWNS the server it tests against; otherwise a live suite passes
-    # with nothing listening on the port, which is what it did.
-    #
-    # Overridable per target:
-    #   main: kit: target: go: test: live: strict: true
-    strict: *false | boolean
+    # Assert live request outcomes, while continuing independent work.
+    # Explicit false retains the legacy exploratory direct-test policy.
+    # Per-target overrides remain available for migration.
+    strict: *true | boolean
 
     # The base URL a live run points at. '' derives it from the spec's first
     # declared server, but ONLY when that is a loopback address.
@@ -585,40 +574,4 @@ main: kit: option: &: {
 
 
 
-# DOCS ITEMS — the third kind. See docs/design/sdkgen-packages.md §20.
-#
-# A docs item is a generation target whose destination is a DOCUMENTATION
-# SYSTEM rather than a language: a static site, a developer-portal catalogue,
-# a hosted service's config. sdkgen ships the kind; the items live in
-# packages, so this spread declares only what EVERY destination needs and
-# leaves the rest to the item's own model file (an unknown key unifies fine).
-#
-# Deliberately NOT copied from the target spread: `ext`, `comment.line` and
-# `module.name` are required there and have no honest value for a site
-# emitting .md, .yml, .css and .svg at once. `title` is defaulted rather than
-# required, so an author is never forced to invent one to make the model
-# compile — the `module.name` trap of §10.1.
-main: kit: docs: &: {
-  name: key()
-  active: *true | boolean
-  title: *'' | string
-
-  # Provenance — see the note on `main: kit: target: &:` above. Written by
-  # `docs add`, read by doctor, `package list` and `package update`.
-  base:     *'' | string
-  origname: *'' | string
-  package:  *'' | string
-
-  # Where the item generates. '' is in-tree, at `<sdk-repo>/<name>/`;
-  # anything else is its own generate() pass rooted there, exactly as for a
-  # target (see explanation/out-of-tree-targets). Out of tree is the normal
-  # case for a docs item: a documentation site usually has its own repo, and
-  # in-tree it would collide with the SDK repo's own README and workflows.
-  output: {
-    path: *'' | string
-    repo: *'' | string
-    create: *true | boolean
-    adopt: *false | boolean
-    sdkrel: *'' | string
-  }
-}
+# Documentation editions extend main.kit.doc through @voxgig/docgen/model/docgen.aon.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/sdkgen",
-  "version": "4.15.0",
+  "version": "4.17.0",
   "main": "dist/sdkgen.js",
   "type": "commonjs",
   "engines": {

package/project/.sdk/src/cmp/go/Config_go.ts

@@ -30,6 +30,7 @@ import {
 
 import {
   formatGoMap,
+  formatGoString,
   goFeatureName,
 } from './utility_go'
 
@@ -133,9 +134,8 @@ const Config = cmp(async function Config(props: any) {
     // 2.1x smaller. MakeConfig still returns the same map, so nothing
     // downstream can tell which representation it got.
     //
-    // JSON.stringify output is a valid Go interpreted string literal: JSON
-    // escapes are a subset of Go's, and Go source is UTF-8 so non-ASCII needs
-    // no escaping. A raw (backtick) literal could NOT be used - the model
+    // JSON escapes work in Go interpreted strings; formatGoString also
+    // escapes BOM characters that Go forbids literally inside source files. A raw (backtick) literal could NOT be used - the model
     // contains backticks in values like `$STRING`.
     if (asData) {
       Content(`package core
@@ -148,7 +148,7 @@ ${pluginImportBlock})
 
 // The API model, emitted as data rather than as a composite literal: see
 // sdkgen rung L1. Parsed by MakeConfig, and parsed once by SharedConfig.
-const configJSON = ${JSON.stringify(configJson)}
+const configJSON = ${formatGoString(configJson)}
 
 // json.Unmarshal decodes EVERY JSON number as float64, but the literal
 // representation emits an integer token as an untyped constant that lands in

package/project/.sdk/src/cmp/go/utility_go.ts

@@ -127,7 +127,7 @@ function formatGoMap(obj: any, indent: number = 0): string {
       return 'map[string]any{}'
     }
     const items = entries
-      .map(([k, v]) => `${padInner}"${k}": ${formatGoValue(v, indent + 1)}`)
+      .map(([k, v]) => `${padInner}${formatGoString(k)}: ${formatGoValue(v, indent + 1)}`)
       .join(',\n')
     return `map[string]any{\n${items},\n${pad}}`
   }
@@ -136,12 +136,19 @@ function formatGoMap(obj: any, indent: number = 0): string {
 }
 
 
+// Go rejects a literal BOM anywhere after the start of a source file,
+// including inside strings. Preserve its value through an escaped literal.
+function formatGoString(value: string): string {
+  return JSON.stringify(value).replace(/\uFEFF/g, '\\ufeff')
+}
+
+
 function formatGoValue(val: any, indent: number = 0): string {
   if (val === null || val === undefined) {
     return 'nil'
   }
   if (typeof val === 'string') {
-    return `"${val.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
+    return formatGoString(val)
   }
   if (typeof val === 'number') {
     if (Number.isInteger(val)) {
@@ -251,6 +258,7 @@ export {
   clean,
   exampleValue,
   formatGoMap,
+  formatGoString,
   formatGoValue,
   goVarName,
   projectPath,

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

@@ -13,7 +13,7 @@ import {
   PUBLISHER_URL,
   packageVersion,
   authorInfo,
-  targetFeatures,
+  targetFeatures, envName,
 } from '@voxgig/sdkgen'
 
 
@@ -81,6 +81,10 @@ const Package = cmp(async function Package(props: any) {
     // directly (no build step), so that is the whole package.
     files: ['src'],
     scripts: {
+      ...(Object.values(model.main.kit.entity || {}).some((e: any) => Object.values(e.op || {}).some((o: any) => (o.points || []).some((p: any) => p.contract && JSON.parse(p.contract.json).live))) ? {
+        'test:live': `${envName(model)}_TEST_LIVE=TRUE node --test test/live.test.js`,
+      } : {}),
+
       'test': 'node --test \'test/**/*.test.js\'',
       'test-some': 'node --experimental-test-isolation=none ' +
         '--test-name-pattern=\"$TEST_PATTERN\" --test \'test/**/*.test.js\'',

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

@@ -96,6 +96,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
 
         Slot({ name: 'directSetup' }, () => {
           Content(`
+function liveScenariosActive() { return ${Object.values(model.main.kit.entity || {}).some((e: any) => Object.values(e.op || {}).some((o: any) => (o.points || []).some((p: any) => p.contract && JSON.parse(p.contract.json).live)))} && process.env.${PROJECTNAME}_TEST_LIVE === 'TRUE' }
 function directSetup(mockres) {
   const calls = []
 
@@ -220,7 +221,7 @@ ${listParamLines}
       assert(listResult.ok === true)
       const listData = listResult.data
       if (!Array.isArray(listData) || listData.length === 0) {
-        return // skip: no entities to load in live mode
+        throw new Error('Live load blocked: discovery returned no usable entities')
       }
       params.id = listData[0].id
 ${ancestorParamLines}
@@ -234,7 +235,8 @@ ${loadParams.map((p: any, i: number) => `      ${jsProp('params', p.name)} = 'di
   }
 
   Content(`
-  test('direct-load-${entity.name}', async () => {
+  test('direct-load-${entity.name}', async (t) => {
+    if (liveScenariosActive()) { t.skip('Covered by live operation scenarios'); return }
     const setup = directSetup({ id: 'direct01' })
     const { client, calls } = setup
 
@@ -248,7 +250,7 @@ ${liveParamsBlock}
     })
 
     assert(result.ok === true)
-    assert(result.status === 200)
+    assert(setup.live ? result.status >= 200 && result.status < 300 : result.status === 200)
     assert(null != result.data)
 
     if (!setup.live) {
@@ -308,7 +310,8 @@ ${mockLines}
   }
 
   Content(`
-  test('direct-list-${entity.name}', async () => {
+  test('direct-list-${entity.name}', async (t) => {
+    if (liveScenariosActive()) { t.skip('Covered by live operation scenarios'); return }
     const setup = directSetup([{ id: 'direct01' }, { id: 'direct02' }])
     const { client, calls } = setup
 
@@ -320,7 +323,7 @@ ${paramsBlock}
     })
 
     assert(result.ok === true)
-    assert(result.status === 200)
+    assert(setup.live ? result.status >= 200 && result.status < 300 : result.status === 200)
     assert(Array.isArray(result.data))
 
     if (!setup.live) {
@@ -359,7 +362,8 @@ function generateDirectGraphqlJs(
     '      assert(calls[0].init.body.includes(\'direct0' + (i + 1) + '\'))\n').join('')
 
   Content(`
-  test('direct-${opname}-${entity.name}', async () => {
+  test('direct-${opname}-${entity.name}', async (t) => {
+    if (liveScenariosActive()) { t.skip('Covered by live operation scenarios'); return }
     const setup = directSetup()
     const { client, calls } = setup
 
@@ -373,7 +377,7 @@ ${mockVarLines || '      // no variables'}
     const result = await client.graphql(${JSON.stringify(doc)}, variables)
 
     assert(result.ok === true)
-    assert(result.status === 200)
+    assert(setup.live ? result.status >= 200 && result.status < 300 : result.status === 200)
     assert(null != result.data)
 
     if (!setup.live) {

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

@@ -171,7 +171,14 @@ function basicSetup(extra) {
 
   idmap = env['${PROJENVNAME}_TEST_${ENTENVNAME}_ENTID']
 
-  if ('TRUE' === env.${PROJENVNAME}_TEST_LIVE) {
+  const live = 'TRUE' === env.${PROJENVNAME}_TEST_LIVE
+  const transport = createLiveTransport()
+  if (live) {
+    const rawIds = process.env['${PROJENVNAME}_TEST_${ENTENVNAME}_ENTID']
+    idmap = rawIds && rawIds.trim() ? JSON.parse(rawIds) : {}
+    if (!idmap || Array.isArray(idmap) || typeof idmap !== 'object') {
+      throw new Error('Live ENTID must be a JSON object')
+    }
     client = new ${model.Name}SDK(merge([
       // FIRST, so the generated fields below win: sdk-test-control.json's
       // test.client.options adds to the live client, it does not redirect it.
@@ -182,7 +189,8 @@ function basicSetup(extra) {
       // the last entry is undefined, and basicSetup is normally called with no
       // argument at all - so a bare 'extra' silently discarded the apikey and
       // server values above and handed the SDK undefined.
-      extra || {}
+      extra || {},
+      { system: { fetch: transport.fetch } }
     ]))
   }
 
@@ -194,6 +202,8 @@ function basicSetup(extra) {
     struct,
     data: entityData,
     explain: 'TRUE' === env.${PROJENVNAME}_TEST_EXPLAIN,
+    live,
+    transport,
     now: Date.now(),
   }
 
@@ -209,7 +219,11 @@ function basicSetup(extra) {
           )
 
           Content(`
+    ${Object.values(model.main.kit.entity || {}).some((e: any) => Object.values(e.op || {}).some((o: any) => (o.points || []).some((p: any) => p.contract && JSON.parse(p.contract.json).live))) ? `if (process.env.${PROJENVNAME}_TEST_LIVE === 'TRUE') { t.skip('Covered by live operation scenarios'); return }` : ''}
     const setup = basicSetup()
+    if (setup.live) {
+      return runLiveEntity(setup, ${JSON.stringify(entity)}, ${JSON.stringify(basicflow)}, '${nom(entity, 'Name')}')
+    }
     const client = setup.client
     const struct = setup.struct
 

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

@@ -0,0 +1,32 @@
+import { cmp, File, Content, entityCollection, envName, serverVariables, serverVarEnv } from '@voxgig/sdkgen'
+import { nom } from '@voxgig/apidef'
+
+const TestLive = cmp(function TestLive(props: any) {
+  const model = props.ctx$.model
+  const plan: any[] = []
+  for (const entity of Object.values(entityCollection(model)) as any[]) {
+    if (entity.active === false) continue
+    for (const [op, operation] of Object.entries(entity.op || {}) as any[]) {
+      for (const point of operation.points || []) {
+        const facts = point.contract ? JSON.parse(point.contract.json) : {}
+        if (model.main.kit.info?.auth === false) facts.security = []
+        const same = operation.points.filter((p: any) => JSON.stringify(p.select || {}) === JSON.stringify(point.select || {}))
+        plan.push({ entity: entity.name, accessor: nom(entity, 'Name'), op,
+          id: point.contract?.id || point.method + ' ' + point.orig, contractVersion: point.contract?.version, kind: point.kind, graphql: point.graphql, path: point.orig, method: point.method,
+          action: point.select?.$action, rename: point.rename, args: point.args, facts, reachable: same.length === 1 })
+      }
+    }
+  }
+  if (!plan.some(p => p.facts.live)) return
+  const server = serverVariables(model).map((v: any) => JSON.stringify(v.name) + ': process.env[' + JSON.stringify(serverVarEnv(envName(model), v.name)) + '] ?? ' + JSON.stringify(v.dflt)).join(', ')
+  File({ name: 'live.test.js' }, () => Content(`const { test } = require('node:test')
+const { SDK } = require('..')
+const { runLiveScenarios } = require('./live-scenarios')
+const { loadEnvLocal } = require('./utility')
+loadEnvLocal(__dirname + '/../.env.local')
+test('live operation coverage', { skip: process.env.${envName(model)}_TEST_LIVE !== 'TRUE' }, async () => {
+  await runLiveScenarios(SDK, ${JSON.stringify(plan, null, 2)}, '${envName(model)}', { server: { ${server} }, secret: process.env.${envName(model)}_SECRET })
+})
+`))
+})
+export { TestLive }

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

@@ -7,6 +7,7 @@ import { cmp, each, Folder, entityCollection,
   TestControl } from '@voxgig/sdkgen'
 
 
+import { TestLive } from './TestLive_js'
 import { TestDirect } from './TestDirect_js'
 import { TestEntity } from './TestEntity_js'
 
@@ -19,6 +20,7 @@ const Test = cmp(function Test(props: any) {
 
     // Write-once: a project's edited control file survives regeneration.
     TestControl({ target, dir: 'test' })
+    TestLive({ target })
 
     Folder({ name: 'entity' }, () => {
       const entity = each(entityCollection(model))

package/project/.sdk/src/cmp/js/fragment/Direct.test.fragment.js

@@ -1,6 +1,6 @@
 
 const envlocal = __dirname + '/../../../.env.local'
-require('dotenv').config({ quiet: true, path: [envlocal] })
+require('../../utility').loadEnvLocal(envlocal)
 
 const { test, describe, afterEach } = require('node:test')
 const assert = require('node:assert')

package/project/.sdk/src/cmp/js/fragment/Entity.test.fragment.js

@@ -1,12 +1,14 @@
 
 const envlocal = __dirname + '/../../../.env.local'
-require('dotenv').config({ quiet: true, path: [envlocal] })
+require('../../utility').loadEnvLocal(envlocal)
 
 const Path = require('node:path')
 const Fs = require('node:fs')
 
 const { test, describe, afterEach } = require('node:test')
 const assert = require('node:assert')
+const { createLiveTransport } = require('../../live-runner')
+const { runLiveEntity } = require('../../live-entity')
 
 
 const { ProjectNameSDK, BaseFeature, stdutil, config } = require('../../..')
@@ -36,7 +38,7 @@ describe('EntityNameEntity', async () => {
   })
 
 
-  test('basic', async () => {
+  test('basic', async (t) => {
     // <[SLOT:basic]>
   })
 })

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

@@ -119,7 +119,7 @@ ${entityLines}
     // That only holds if the run pass can SEE a parse failure — and without
     // these two patterns it could not, so a syntax error in a runnable example
     // would have passed both gates.
-    private const FATAL = '/(Call to undefined method|Call to undefined function|Call to a member function|ArgumentCountError|Too few arguments|Undefined constant|Uncaught TypeError|ParseError|Parse error)/';
+    private const FATAL = '/(Call to undefined method|Call to undefined function|Call to a member function|ArgumentCountError|Too few arguments|Undefined constant|Uncaught TypeError|ParseError|Parse error|Allowed memory size|Cannot use object of type)/';
 
     // The three documentation sources this gate covers.
     private function docs(): array
@@ -374,20 +374,14 @@ ${entityLines}
 
             $driver = $dir . '/_driver.php';
             file_put_contents($driver, $this->batchDriver($paths));
-            $out = [];
-            $rc = 0;
-            exec('php ' . escapeshellarg($driver) . ' 2>&1', $out, $rc);
-            $text = implode("\\n", $out);
+            [$text, $rc] = $this->runOutput('php ' . escapeshellarg($driver));
 
             foreach ($runnable as $i => $blk) {
                 $seg = $this->batchSegment($text, $i);
                 if ($seg === null) {
                     // No END marker: the batch died inside or before this
                     // snippet. Re-run it alone so the verdict is isolated.
-                    $solo = [];
-                    $src = 0;
-                    exec('php ' . escapeshellarg($paths[$i]) . ' 2>&1', $solo, $src);
-                    $seg = implode("\\n", $solo);
+                    [$seg, $src] = $this->runOutput('php ' . escapeshellarg($paths[$i]));
                     $rc = $src;
                 }
                 if (preg_match(self::FATAL, $seg) === 1) {
@@ -410,6 +404,33 @@ ${entityLines}
      * in flight, so the harness can tell "this one died" from "the batch
      * stopped before reaching it", and re-run only what it must.
      */
+    private function runOutput(string $command): array
+    {
+        // A printed entity can include the client graph. Scan the stream;
+        // retaining all output (and a second joined copy) exhausts PHP's heap.
+        $process = proc_open($command, [1 => ['pipe', 'w'], 2 => ['redirect', 1]], $pipes);
+        if (!is_resource($process)) throw new \RuntimeException('Could not run README example');
+        $summary = '';
+        $tail = '';
+        $reported = false;
+        while (($chunk = fgets($pipes[1], 8192)) !== false) {
+            if (preg_match('/@@VOX(BEGIN|END) [0-9]+/', $chunk, $marker)) {
+                $summary .= "\\n" . $marker[0] . "\\n";
+                if ($marker[1] === 'BEGIN') $reported = false;
+                $tail = '';
+            }
+            $window = $tail . $chunk;
+            if (!$reported && preg_match(self::FATAL, $window, $error, PREG_OFFSET_CAPTURE)) {
+                $summary .= "\\n" . substr($window, max(0, $error[0][1] - 100), 512) . "\\n";
+                $reported = true;
+            }
+            // Keep enough overlap to catch an error phrase split by fgets.
+            $tail = substr($window, -256);
+        }
+        fclose($pipes[1]);
+        return [$summary, proc_close($process)];
+    }
+
     private function batchDriver(array $paths): string
     {
         // NOWDOC, not heredoc. The driver is PHP source that must survive

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

@@ -21,7 +21,12 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   // Pick an entity with a real op (prefer a read op) — never fabricate a
   // `load` on an op-less entity like Cloudsmith's `Abort`. primaryOp is null
   // only when NO entity exposes any op (a direct()-only SDK).
-  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
+  // Prefer records that the offline store can seed and look up by ID.
+  // An ID-less singleton has no key for the mock transport to resolve.
+  const seedable = Object.fromEntries(Object.entries(entity).filter(
+    ([, value]: any) => entityIdField(value) && Object.keys(value.op || {}).length))
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(
+    Object.keys(seedable).length ? seedable : entity)
   const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
   // Model-driven id key: null when the entity has no id-like field.
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
@@ -51,10 +56,10 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   // The op-driven test-mode line, shown only when the SDK has an entity op.
   // A direct()-only SDK (no ops anywhere) shows a direct() call instead.
   const testModeExample = primaryOp
-    ? `// Entity ops return the ENTITY (throws on error);
+    ? `// ${primaryOp === 'list' ? 'list() returns entity instances' : 'Entity ops return the ENTITY'} (throws on error);
 // call data_get() for the mock record.
 $${eName.toLowerCase()} = $client->${phpEntityAccessor(eName)}()->${primaryOp}(${testCallArg});
-print_r($${eName.toLowerCase()});`
+print_r(${primaryOp === 'list' ? `array_map(fn($item) => $item->data_get(), $${eName.toLowerCase()})` : `$${eName.toLowerCase()}->data_get()`});`
     : `$result = $client->direct(["path" => "/api/resource", "method" => "GET"]);
 print_r($result);`
 

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

@@ -81,9 +81,10 @@ $client = ${ctor};
 
 \`\`\`php
 try {
-    // list() returns an array of ${eName} records — iterate directly.
+    // list() returns entity instances; data_get() reads each record.
     $${eName.toLowerCase()}s = $client->${phpEntityAccessor(eName)}()->list();
-    foreach ($${eName.toLowerCase()}s as $item) {
+    foreach ($${eName.toLowerCase()}s as $record) {
+        $item = $record->data_get();
         echo ${itemPrint} . "\\n";
     }
 } catch (\\Throwable $err) {
@@ -122,7 +123,7 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
 try {
     // load() returns the ENTITY — call data_get() for the ${neName} record (throws on error).
     $${neVar} = $client->${phpEntityAccessor(neName)}()->load([${neMatch.join(', ')}]);
-    print_r($${neVar});
+    print_r($${neVar}->data_get());
 } catch (\\Throwable $err) {
     echo "Error: " . $err->getMessage();
 }
@@ -150,7 +151,7 @@ try {
 try {
     // load() returns the ENTITY — call data_get() for the ${eName} record (throws on error).
     $${eName.toLowerCase()} = $client->${phpEntityAccessor(eName)}()->load(${loadArg});
-    print_r($${eName.toLowerCase()});
+    print_r($${eName.toLowerCase()}->data_get());
 } catch (\\Throwable $err) {
     echo "Error: " . $err->getMessage();
 }

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

@@ -52,7 +52,7 @@ $client = ${ctor};
     if (opnames.includes('list')) {
       Content(`// List all ${eName.toLowerCase()}s (returns an array; throws on error)
 $${eName.toLowerCase()}s = $client->${phpEntityAccessor(eName)}()->list();
-print_r($${eName.toLowerCase()}s);
+print_r(array_map(fn($item) => $item->data_get(), $${eName.toLowerCase()}s));
 `)
       hasCall = true
     }
@@ -73,7 +73,7 @@ print_r($${eName.toLowerCase()}s);
       Content(`
 // Load a specific ${eName.toLowerCase()} (returns the ENTITY; call data_get() for the record; throws on error)
 $${eName.toLowerCase()} = $client->${phpEntityAccessor(eName)}()->load(${loadArg});
-print_r($${eName.toLowerCase()});
+print_r($${eName.toLowerCase()}->data_get());
 `)
       hasCall = true
     }

package/project/.sdk/src/cmp/ts/Package_ts.ts

@@ -13,7 +13,7 @@ import {
   PUBLISHER_URL,
   packageVersion,
   authorInfo,
-  targetFeatures,
+  targetFeatures, envName,
 } from '@voxgig/sdkgen'
 
 
@@ -83,6 +83,10 @@ const Package = cmp(async function Package(props: any) {
     // are always included by npm and need no entry.
     files: ['dist', 'src'],
     scripts: {
+      ...(Object.values(model.main.kit.entity || {}).some((e: any) => Object.values(e.op || {}).some((o: any) => (o.points || []).some((p: any) => p.contract && JSON.parse(p.contract.json).live))) ? {
+        'test:live': `npm run build && ${envName(model)}_TEST_LIVE=TRUE node --test dist-test/live.test.js`,
+      } : {}),
+
       // `test` and `test-coverage` run the COMPILED suite in dist-test/, which
       // a fresh clone does not have — the glob then matches nothing and the
       // run reports "tests 0, pass 0, fail 0" and exits 0. A green suite that

package/project/.sdk/src/cmp/ts/ReadmeHowto_ts.ts

@@ -190,6 +190,11 @@ Then run:
 cd ts && npm test
 \`\`\`
 
+Live entity tests continue independent operations after errors and attempt
+supported cleanup. Their final result reports failures and missing prerequisites
+after the remaining work completes. The model and test inputs determine which
+API operations the generated scenarios cover.
+
 `)
 
 })

package/project/.sdk/src/cmp/ts/TestDirect_ts.ts

@@ -104,6 +104,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
 
         Slot({ name: 'directSetup' }, () => {
           Content(`
+function liveScenariosActive() { return ${Object.values(model.main.kit.entity || {}).some((e: any) => Object.values(e.op || {}).some((o: any) => (o.points || []).some((p: any) => p.contract && JSON.parse(p.contract.json).live)))} && process.env.${PROJECTNAME}_TEST_LIVE === 'TRUE' }
 function directSetup(mockres?: any) {
   const calls: any[] = []
 
@@ -115,10 +116,11 @@ function directSetup(mockres?: any) {
   const live = 'TRUE' === env.${PROJECTNAME}_TEST_LIVE
 
   if (live) {
+    const transport = createLiveTransport()
     // Merged so the generated fields win: sdk-test-control.json's
     // test.client.options adds to the live client, it does not redirect it.
     const client = new ${nom(model.const, 'Name')}SDK(
-      Object.assign({}, liveClientOptions(), {${apikeyLiveField}${serverLiveField}
+      Object.assign({}, liveClientOptions(), { system: { fetch: transport.fetch },${apikeyLiveField}${serverLiveField}
       }))
 
     let idmap: any = env['${entidEnvVar}']
@@ -126,7 +128,7 @@ function directSetup(mockres?: any) {
       idmap = JSON.parse(idmap)
     }
 
-    return { client, calls, live, idmap }
+    return { client, calls, live, idmap, transport }
   }
 
   const mockFetch = async (url: string, init: any) => {
@@ -246,7 +248,7 @@ ${varAsserts}`
       // "compare the live server against the mock's script" - a suite that
       // could not pass against any real API, including this project's own.
       assert(result.ok === true,
-        'live request failed: ' + result.status + ' ' + JSON.stringify(result.data))
+        'Live request failed: HTTP ' + result.status)
       assert(result.status >= 200 && result.status < 300)
       assert(null != result.data)
     } else {
@@ -263,6 +265,7 @@ ${offlineChecks}    }`
 
   Content(`
   test('direct-${opname}-${entity.name}', async (t: any) => {
+    if (liveScenariosActive()) { t.skip('Covered by live operation scenarios'); return }
     const setup = directSetup()
     if (maybeSkipControl(t, 'direct', 'direct-${opname}-${entity.name}', setup.live)) return
 ${skipMissingLine}    const { client, calls } = setup
@@ -418,16 +421,15 @@ ${liveQueryPrefix}      const listResult: any = await client.direct({
 ${listParamLines}
         },
       })
-      if (!listResult.ok) {
-        return // skip: list call failed (likely synthetic IDs against live API)
-      }
+      assert(listResult.ok && listResult.status >= 200 && listResult.status < 300,
+        'Live list discovery failed')
       const listArr = unwrapListData(listResult.data)
       if (null == listArr || listArr.length === 0) {
-        return // skip: no entities to load in live mode
+        throw new Error('Live load blocked: discovery returned no entities')
       }
       const candidateId = ${jsOptProp('listArr[0]', idParamName)} ?? listArr[0]?.id
       if (null == candidateId) {
-        return // skip: list response shape does not expose load identifier
+        throw new Error('Live load blocked: discovery returned no usable identity')
       }
       ${jsProp('params', idParamName)} = candidateId
 ${ancestorParamLines}
@@ -479,7 +481,7 @@ ${paramAsserts}`
       // "compare the live server against the mock's script" - a suite that
       // could not pass against any real API, including this project's own.
       assert(result.ok === true,
-        'live request failed: ' + result.status + ' ' + JSON.stringify(result.data))
+        'Live request failed: HTTP ' + result.status)
       assert(result.status >= 200 && result.status < 300)
       assert(null != result.data)
     } else {
@@ -496,6 +498,7 @@ ${offlineChecks}    }`
 
   Content(`
   test('direct-load-${entity.name}', async (t: any) => {
+    if (liveScenariosActive()) { t.skip('Covered by live operation scenarios'); return }
     const setup = directSetup({ id: 'direct01' })
     if (maybeSkipControl(t, 'direct', 'direct-load-${entity.name}', setup.live)) return
 ${skipMissingLine}    const { client, calls } = setup
@@ -607,9 +610,9 @@ ${paramAsserts}`
       // "compare the live server against the mock's script" - a suite that
       // could not pass against any real API, including this project's own.
       assert(result.ok === true,
-        'live request failed: ' + result.status + ' ' + JSON.stringify(result.data))
+        'Live request failed: HTTP ' + result.status)
       assert(result.status >= 200 && result.status < 300)
-      assert(null != result.data)
+      assert(Array.isArray(unwrapListData(result.data)), 'Expected live list response')
     } else {
 ${offlineChecks}    }` :
     `    if (setup.live) {
@@ -628,6 +631,7 @@ ${offlineChecks}    }`
 
   Content(`
   test('direct-list-${entity.name}', async (t: any) => {
+    if (liveScenariosActive()) { t.skip('Covered by live operation scenarios'); return }
     const setup = directSetup([{ id: 'direct01' }, { id: 'direct02' }])
     if (maybeSkipControl(t, 'direct', 'direct-list-${entity.name}', setup.live)) return
 ${skipMissingLine}    const { client, calls } = setup