@voxgig/sdkgen 1.2.1 → 1.3.1

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

@@ -0,0 +1,81 @@
+
+import { cmp, Content, File } from '@voxgig/sdkgen'
+
+
+// Generates ts/test/ReadmeExample.test.ts — a test that reads the
+// repo's top-level README.md at runtime, extracts the first TS code
+// block under "## Quickstart", transforms `new <Name>SDK(...)`
+// to `<Name>SDK.test()` so it runs offline, evaluates the rest, and
+// asserts no error. Catches drift between the README quickstart and
+// the real SDK API.
+const ReadmeExampleTest = cmp(function ReadmeExampleTest(props: any) {
+  const { ctx$: { model } } = props
+  const Name = model.const.Name
+
+  File({ name: 'ReadmeExample.test.ts' }, () => {
+    Content(`// Verifies the README's lead-language quickstart still runs.
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert'
+import * as Fs from 'node:fs'
+import * as Path from 'node:path'
+
+import { ${Name}SDK } from '..'
+
+
+function findFirstTsBlock(md: string, sectionHeading: string): string | null {
+  const escapedHeading = sectionHeading.replace(/[.*+?^\${}()|[\\]\\\\]/g, '\\\\$&')
+  const re = new RegExp('##\\\\s+' + escapedHeading + '[\\\\s\\\\S]*?\`\`\`ts\\\\n([\\\\s\\\\S]*?)\`\`\`')
+  const m = md.match(re)
+  return m ? m[1] : null
+}
+
+
+function transformForTestMode(code: string, name: string): string {
+  // Strip import lines — symbols come from the test's outer scope.
+  let out = code.replace(/^\\s*import\\s+[^;\\n]+;?\\s*$/gm, '')
+  // Swap real client construction for test mode (no network, no auth).
+  out = out.replace(new RegExp('new\\\\s+' + name + 'SDK\\\\([^)]*\\\\)', 'g'), name + 'SDK.test()')
+  return out
+}
+
+
+describe('README example', () => {
+  it('lead-language quickstart runs in test mode', async () => {
+    const readmePath = Path.join(__dirname, '..', '..', 'README.md')
+    const md = Fs.readFileSync(readmePath, 'utf8')
+
+    const block = findFirstTsBlock(md, 'Quickstart')
+    assert(block, 'No TypeScript code block found under "## Quickstart" in README.md')
+
+    const code = transformForTestMode(block, '${Name}')
+
+    // Run the (transformed) example. Async, so wrap in AsyncFunction.
+    const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor
+    const silentConsole = { log: () => {}, error: () => {}, warn: () => {} }
+    const runner = new AsyncFunction('${Name}SDK', 'console', code)
+
+    // The example should at least parse and have a valid call shape
+    // (every method exists on the SDK and accepts the args shown). A
+    // "Not found" / 404 from test mode means the SDK accepted the call
+    // but there's no fixture for that match — that's a test-data gap,
+    // not a README bug, so it's OK. Everything else (TypeError,
+    // ReferenceError, SyntaxError) means the README example is out of
+    // sync with the real SDK API and the test should fail.
+    try {
+      await runner(${Name}SDK, silentConsole)
+    } catch (err: any) {
+      const msg = String(err?.message ?? err)
+      if (/\\b(404|Not found)\\b/i.test(msg)) return
+      throw err
+    }
+  })
+})
+`)
+  })
+})
+
+
+export {
+  ReadmeExampleTest
+}

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

@@ -0,0 +1,446 @@
+
+import { cmp, Content, File } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+// Generates ts/test/readme_examples.test.ts — a COMPLETENESS GATE that
+// guarantees every fenced \`\`\`ts code example across all THREE docs (the
+// repo root README.md, this target's per-language README.md, and its
+// REFERENCE.md) is unit-tested. Every block from every doc is:
+//
+//  (1) TYPE-CHECKED against the real SDK types with the repo's local
+//      \`tsc --noEmit\`. To stay robust against tsc suppressing all semantic
+//      diagnostics program-wide whenever one file has a syntax error, blocks
+//      are compiled one-file-per-block in a fixpoint: compile the batch, drop
+//      the ones that error, recompile the rest, until a pass is clean — so a
+//      real type bug can never hide behind a neighbouring illustration's
+//      syntax error.
+//  (2) EXECUTED, if RUNNABLE (constructs \`new <Sdk>SDK\` / \`<Sdk>SDK.test\`
+//      or drives \`client.\`), by rewriting it to a seeded test-mode client
+//      and running it offline. A programming error (undefined method, wrong
+//      arity, bad symbol) fails; only a 404 / "Not found" domain error for an
+//      unseeded id is tolerated. This now runs for ALL THREE docs (previously
+//      only the root README executed).
+//  (3) PARTITIONED into exactly one of { executed, typechecked-only,
+//      illustration } with the counts asserted to sum to the total. A block
+//      that does NOT type-check is only allowed if it matches the NARROW
+//      illustration allowlist (bare method-signature \`?:\`, \`/* placeholder */\`
+//      value, or a type-SHAPE block). Any other non-type-checking block FAILS
+//      the test, quoting the block — it is NEVER silently skipped. A per-doc
+//      summary line makes the coverage visible in the test output.
+const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
+  const { ctx$: { model } } = props
+  const Name = model.const.Name
+
+  // Seed a fixture for every active entity so list()/load() resolve
+  // offline in test mode with no network. Keyed by the entity's model
+  // name (the same key the test-mode transport looks up).
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const seedEntities: Record<string, any> = {}
+  Object.values(entity).forEach((e: any) => {
+    if (e && false !== e.active && 'string' === typeof e.name) {
+      seedEntities[e.name] = { test01: { id: 'test01' } }
+    }
+  })
+  const seedLiteral = JSON.stringify({ entity: seedEntities })
+
+  File({ name: 'readme_examples.test.ts' }, () => {
+    Content(`// Completeness gate over every TypeScript example in this SDK's docs.
+//
+// Covers all THREE documentation files — the repo root README.md, this
+// target's README.md, and its REFERENCE.md. Every fenced \`\`\`ts block in
+// every one is put through the same pipeline:
+//
+//  (1) TYPE-CHECK — every block is compiled with the repo's local
+//      \`tsc --noEmit\` against the real SDK types. A block that misuses the
+//      SDK types (e.g. \`.data\` on a \`list()\` array, or a string id where a
+//      number is required) is a compile error.
+//  (2) EXECUTE — every RUNNABLE block (one that constructs the SDK or
+//      drives \`client.\`) is rewritten to seeded test mode, transpiled to
+//      JS, and run offline. A programming error (undefined method,
+//      wrong-arg-count, bad symbol) fails the test; only an expected domain
+//      error (a 404 / "Not found" for an unseeded id) is tolerated.
+//  (3) COMPLETENESS — every block is partitioned into exactly one of
+//      { executed, typechecked-only, illustration } and the counts must sum
+//      to the total. A block that does NOT type-check is allowed ONLY if it
+//      matches the NARROW illustration allowlist (a bare method signature
+//      \`?:\`, a \`/* placeholder */\` value, or a type-SHAPE block). Any other
+//      non-type-checking block FAILS the test, quoting the block — it is
+//      never silently skipped.
+//
+// Generated by @voxgig/sdkgen — do not edit by hand.
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert'
+import * as Fs from 'node:fs'
+import * as Path from 'node:path'
+import { createRequire } from 'node:module'
+import { spawnSync } from 'node:child_process'
+
+import { ${Name}SDK } from '..'
+
+
+const SDK_NAME = '${Name}SDK'
+
+// A fixture for every entity, so list()/load() resolve offline with no
+// network. Snippet client construction is rewritten to seed this.
+const TEST_SEED = ${seedLiteral}
+const SEED_ARG = JSON.stringify(TEST_SEED)
+const SEEDED_CTOR = SDK_NAME + '.test(' + SEED_ARG + ')'
+
+
+// The three docs this gate covers, resolved relative to dist-test/.
+const DOCS: Array<{ label: string; key: string; path: string }> = [
+  { label: 'root README.md', key: 'root_readme', path: Path.join(__dirname, '..', '..', 'README.md') },
+  { label: 'ts/README.md', key: 'lang_readme', path: Path.join(__dirname, '..', 'README.md') },
+  { label: 'ts/REFERENCE.md', key: 'reference', path: Path.join(__dirname, '..', 'REFERENCE.md') },
+]
+
+
+// Pull out the body of every \`\`\`ts fenced code block.
+function extractTsBlocks(md: string): string[] {
+  const blocks: string[] = []
+  const re = /\`\`\`ts\\n([\\s\\S]*?)\`\`\`/g
+  let m: RegExpExecArray | null
+  while ((m = re.exec(md)) !== null) {
+    blocks.push(m[1])
+  }
+  return blocks
+}
+
+
+// Snippet import lines reference the published package name, which is not
+// resolvable from inside the repo; the SDK symbol is supplied by the one
+// module-level import we emit / inject instead.
+function stripImports(code: string): string {
+  return code.replace(/^\\s*import\\s+[^\\n]*$/gm, '')
+}
+
+
+// A block is an ILLUSTRATION shape — documentation, not runnable code — if
+// it matches this NARROW allowlist. These are the ONLY shapes a
+// non-type-checking block is allowed to be; anything else that fails to
+// type-check is a real bug and fails the gate. Three shapes:
+//   1. a bare method / constructor signature with a typed-parameter
+//      signature ("?:", e.g. \`options?: { base?: string }\`);
+//   2. a placeholder-comment value ("/*", e.g. \`field: /* string */\`);
+//   3. a type-SHAPE block that lists fields as \`name: TypeKeyword\` with the
+//      type standing alone as the value — e.g. the DirectResult / FetchDef
+//      shape \`{ ok: boolean; status: number; ... }\`. Those bare keywords
+//      are undeclared VALUES (TS2693 "only refers to a type"). Matched
+//      only at the START of a line, so a genuine annotation inside runnable
+//      code (e.g. \`(ctx: any) => ...\`) is NOT matched.
+const SHAPE_ILLUSTRATION =
+  /^\\s*[A-Za-z_$][\\w$]*\\??\\s*:\\s*(?:boolean|number|string|object|any|unknown|never|void|symbol|bigint|Record<|Partial<|Array<|Map<|Set<)/m
+function isIllustrationShape(code: string): boolean {
+  if (code.includes('?:')) {
+    return true
+  }
+  if (code.includes('/*')) {
+    return true
+  }
+  if (SHAPE_ILLUSTRATION.test(code)) {
+    return true
+  }
+  return false
+}
+
+
+// A block is RUNNABLE if it constructs the SDK (\`new <Sdk>SDK\` /
+// \`<Sdk>SDK.test\`) or drives a \`client.\` — those are the blocks the execute
+// gate rewrites to seeded test mode and runs.
+function isRunnable(code: string): boolean {
+  return (
+    /new\\s+${Name}SDK\\b/.test(code) ||
+    /\\b${Name}SDK\\.test\\b/.test(code) ||
+    /\\bclient\\s*\\./.test(code)
+  )
+}
+
+
+// Wrap ONE block as a self-contained temp module: the block goes in its own
+// scope inside an async function with a shared seeded \`client\`.
+function buildSnippetModule(block: string): string {
+  const inner = stripImports(block).split('\\n').map((l) => '    ' + l).join('\\n')
+  return [
+    "import { " + SDK_NAME + " } from '..'",
+    '',
+    'async function __ex() {',
+    // Shared client for snippets that reference \`client\` without constructing
+    // one (e.g. the direct() example).
+    '  const client = ' + SDK_NAME + '.test()',
+    '  void client',
+    '  {',
+    inner,
+    '  }',
+    '}',
+    'void __ex',
+    '',
+  ].join('\\n')
+}
+
+
+// Compile a batch of blocks in ONE tsc pass — one temp file per block, so
+// each is an isolated program entry — and return which snippet indices
+// errored. NOTE: tsc suppresses ALL semantic diagnostics program-wide as
+// soon as any file has a SYNTAX error, so a single batch cannot be trusted;
+// \`typeCheckBlocks\` drives this in a fixpoint that removes erroring blocks
+// and recompiles the rest until a pass is clean.
+function compileBatch(indices: number[], blocks: string[], key: string): {
+  errored: Set<number>; raw: string; unattributed: boolean
+} {
+  const tsDir = Path.join(__dirname, '..')
+  const testDir = Path.join(tsDir, 'test')
+  // Leading dot: TypeScript wildcard includes skip dot-files, so these temp
+  // files are never swept into the normal build.
+  const files: string[] = []
+
+  try {
+    for (const i of indices) {
+      const f = Path.join(testDir, '.examples_' + key + '_snippet' + i + '.gen.ts')
+      Fs.writeFileSync(f, buildSnippetModule(blocks[i]), 'utf8')
+      files.push(f)
+    }
+
+    const requireFrom = createRequire(__filename)
+    const tsc = requireFrom.resolve('typescript/bin/tsc')
+
+    const res = spawnSync(process.execPath, [
+      tsc,
+      '--noEmit',
+      '--strict',
+      '--pretty', 'false',
+      '--target', 'ES2022',
+      '--module', 'nodenext',
+      '--moduleResolution', 'nodenext',
+      '--esModuleInterop',
+      '--resolveJsonModule',
+      '--skipLibCheck',
+      '--types', 'node',
+      ...files,
+    ], { cwd: tsDir, encoding: 'utf8' })
+
+    const raw = ((res.stdout || '') + (res.stderr || '')).trim()
+    const errored = new Set<number>()
+    let unattributed = false
+
+    if (0 !== res.status) {
+      for (const line of raw.split('\\n')) {
+        const m = /_snippet(\\d+)\\.gen\\.ts\\(\\d+,\\d+\\):\\s*error/.exec(line)
+        if (null == m) {
+          // A genuine error diagnostic not attributable to a snippet file
+          // (e.g. inside the SDK itself) is an anomaly.
+          if (/:\\s*error\\s+TS\\d+/.test(line)) {
+            unattributed = true
+          }
+          continue
+        }
+        errored.add(parseInt(m[1], 10))
+      }
+    }
+
+    return { errored, raw, unattributed }
+  } finally {
+    for (const f of files) {
+      Fs.rmSync(f, { force: true })
+    }
+  }
+}
+
+
+// Determine, robustly, which of a doc's blocks fail to type-check. Because
+// one syntax error suppresses semantic diagnostics for the whole batch, we
+// iterate: compile the still-unresolved blocks, record the ones that
+// errored, drop them, and recompile the rest — until a pass reports no
+// errors. Each erroring pass strictly shrinks the working set, so this
+// terminates. \`globalError\` flags an unattributable tsc error, surfaced
+// verbatim by the caller.
+function typeCheckBlocks(blocks: string[], key: string): {
+  failing: Set<number>; raw: string; globalError: boolean
+} {
+  const failing = new Set<number>()
+  const raws: string[] = []
+  let globalError = false
+  let remaining = blocks.map((_b, i) => i)
+
+  // Guard: at most one pass per block plus a final clean pass.
+  for (let pass = 0; pass <= blocks.length && 0 < remaining.length; pass++) {
+    const { errored, raw, unattributed } = compileBatch(remaining, blocks, key)
+    raws.push(raw)
+    if (unattributed) {
+      globalError = true
+    }
+    if (0 === errored.size) {
+      break
+    }
+    for (const i of errored) {
+      failing.add(i)
+    }
+    remaining = remaining.filter((i) => !errored.has(i))
+  }
+
+  return { failing, raw: raws.filter(Boolean).join('\\n'), globalError }
+}
+
+
+// Turn a documented snippet into an offline-runnable one: strip imports,
+// rewrite real client construction (\`new <Sdk>SDK(...)\` and any
+// \`<Sdk>SDK.test(...)\`) to a seeded test-mode client, and give snippets
+// that reference \`client\` without constructing one a shared seeded client.
+function rewriteForRun(code: string): string {
+  let out = stripImports(code)
+  out = out.replace(/new\\s+${Name}SDK\\s*\\([^)]*\\)/g, () => SEEDED_CTOR)
+  out = out.replace(/${Name}SDK\\.test\\s*\\([^)]*\\)/g, () => SEEDED_CTOR)
+  if (/\\bclient\\b/.test(out) && !/\\b(?:const|let|var)\\s+client\\b/.test(out)) {
+    out = 'const client = ' + SEEDED_CTOR + '\\n' + out
+  }
+  return out
+}
+
+
+// Run every runnable, non-illustration block from a doc offline in seeded
+// test mode. Returns a list of failure descriptions (empty === all passed).
+async function executeBlocks(blocks: string[]): Promise<string[]> {
+  const requireFrom = createRequire(__filename)
+  const ts = requireFrom('typescript')
+
+  const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor
+  const silentConsole = { log() {}, error() {}, warn() {}, info() {} }
+
+  const failures: string[] = []
+
+  for (let i = 0; i < blocks.length; i++) {
+    // Illustration shapes are documentation, not runnable code.
+    if (!isRunnable(blocks[i]) || isIllustrationShape(blocks[i])) {
+      continue
+    }
+
+    const src = rewriteForRun(blocks[i])
+    if ('' === src.trim()) {
+      continue
+    }
+
+    // Compile the snippet to JS (strips type annotations) so it runs under
+    // node exactly as a real caller would.
+    const js = ts.transpileModule(src, {
+      compilerOptions: {
+        target: ts.ScriptTarget.ES2020,
+        module: ts.ModuleKind.ESNext,
+      },
+    }).outputText
+
+    let runner: any
+    try {
+      runner = new AsyncFunction(SDK_NAME, 'console', js)
+    } catch (err: any) {
+      failures.push('snippet ' + i + ' failed to compile as runnable JS: ' +
+        String((err && err.message) || err))
+      continue
+    }
+
+    try {
+      await runner(${Name}SDK, silentConsole)
+    } catch (err: any) {
+      const msg = String((err && err.message) || err)
+      // Tolerate the one expected domain error: no fixture seeded for the
+      // requested id (a 404 / "Not found" from test mode). A programming
+      // error (undefined method/symbol, wrong arg count) is a real doc bug
+      // and is NOT tolerated.
+      if (/\\b(?:404|not found)\\b/i.test(msg)) {
+        continue
+      }
+      failures.push('snippet ' + i + ' threw at runtime: ' + msg)
+    }
+  }
+
+  return failures
+}
+
+
+function indentBlock(code: string): string {
+  return code.replace(/^/gm, '    ').replace(/\\s+$/, '')
+}
+
+
+describe('README examples', () => {
+  for (const doc of DOCS) {
+    it(doc.label + ' — every example type-checks or is a known illustration', () => {
+      // A target without this doc has nothing to check.
+      if (!Fs.existsSync(doc.path)) {
+        return
+      }
+      const md = Fs.readFileSync(doc.path, 'utf8')
+      const blocks = extractTsBlocks(md)
+      assert(blocks.length > 0, 'No TypeScript code blocks found in ' + doc.label)
+
+      const { failing, raw, globalError } = typeCheckBlocks(blocks, doc.key)
+      assert(!globalError,
+        'tsc reported an error outside any snippet in ' + doc.label +
+        ' — the harness could not attribute it:\\n\\n' + raw + '\\n')
+
+      let executed = 0
+      let typecheckedOnly = 0
+      let illustration = 0
+      const unrecognized: string[] = []
+
+      blocks.forEach((b, i) => {
+        const typechecks = !failing.has(i)
+        const shape = isIllustrationShape(b)
+        const runnable = isRunnable(b) && !shape
+
+        if (!typechecks && shape) {
+          illustration++
+        } else if (!typechecks && !shape) {
+          unrecognized.push('  snippet ' + i + ':\\n' + indentBlock(b))
+        } else if (typechecks && runnable) {
+          executed++
+        } else {
+          typecheckedOnly++
+        }
+      })
+
+      // Emit the coverage summary FIRST so it is always visible, even when
+      // an assertion below fails.
+      console.log('README examples [' + doc.label + ']: total=' + blocks.length +
+        ' executed=' + executed + ' typechecked=' + typecheckedOnly +
+        ' illustration=' + illustration)
+
+      assert.strictEqual(unrecognized.length, 0,
+        'These ' + doc.label + ' \`\`\`ts blocks neither type-check nor match the ' +
+        'illustration allowlist. Fix the snippet (or the SDK), or — if it is ' +
+        'genuinely illustrative — reshape it to the allowlist:\\n\\n' +
+        unrecognized.join('\\n\\n') + '\\n\\ntsc output:\\n' + raw + '\\n')
+
+      assert.strictEqual(blocks.length, executed + typecheckedOnly + illustration,
+        'completeness partition mismatch for ' + doc.label + ': ' + blocks.length +
+        ' total != ' + executed + ' executed + ' + typecheckedOnly +
+        ' typechecked + ' + illustration + ' illustration')
+    })
+
+    it(doc.label + ' — every runnable example executes in test mode', async () => {
+      if (!Fs.existsSync(doc.path)) {
+        return
+      }
+      const md = Fs.readFileSync(doc.path, 'utf8')
+      const blocks = extractTsBlocks(md)
+      assert(blocks.length > 0, 'No TypeScript code blocks found in ' + doc.label)
+
+      const failures = await executeBlocks(blocks)
+      assert.strictEqual(failures.length, 0,
+        doc.label + ' runnable TypeScript snippets failed to run in test mode:\\n\\n' +
+        failures.join('\\n') + '\\n')
+    })
+  }
+})
+`)
+  })
+})
+
+
+export {
+  ReadmeExamplesTest
+}

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, packageName } from '@voxgig/sdkgen'
 
 
 const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
@@ -21,7 +21,7 @@ ${model.name}/
 Import the SDK from the package root:
 
 \`\`\`ts
-import { ${model.Name}SDK } from '${model.name}'
+import { ${model.Name}SDK } from '${packageName(model, target.name)}'
 \`\`\`
 
 `)

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

@@ -1,21 +1,64 @@
 
-import { cmp, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, entityIdField, entityDataIdField, entityPrimaryOp, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
+  nom,
 } from '@voxgig/apidef'
 
+import { exampleValue } from './utility_ts'
+
 
 const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const { target, ctx$: { model } } = props
 
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const exampleEntity = Object.values(entity || {}).find((e: any) => e && e.active !== false) as any
+  const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
+  // Variable-safe lowercase name (a `Delete` entity must not bind `delete`).
+  const eVar = safeVarName(eName.toLowerCase(), 'ts')
+
+  // Drive the test-mode / stateful examples off the entity's PRIMARY op — an op
+  // it actually exposes — never a hardcoded `load` a create-only entity lacks.
+  const primaryOp = exampleEntity ? (entityPrimaryOp(exampleEntity) || 'load') : 'load'
+  const primaryOpDef = exampleEntity && exampleEntity.op && exampleEntity.op[primaryOp]
+  const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+  // Model-driven id key: `idF` is the entity's id-like MATCH field name, or null
+  // when it has none. `dataIdF` is the id on the RETURNED record's data type —
+  // reading `.id` off a record whose data type has none is a TS2339.
+  const idF = exampleEntity ? entityIdField(exampleEntity) : null
+  const dataIdF = exampleEntity ? entityDataIdField(exampleEntity) : null
+
+  // A type-correct, language-idiomatic argument for the primary op call.
+  const primaryArg = (idPlaceholder: string): string => {
+    if (!exampleEntity) return ''
+    if ('list' === primaryOp) return ''
+    if (isMatchOp) {
+      return idF ? `{ ${idF}: ${exampleValue(exampleEntity, primaryOpDef, idF, idPlaceholder)} }` : ''
+    }
+    // create / update: a body of the required writable fields.
+    const items = opRequestShape(exampleEntity, primaryOp).items
+      .filter((it: any) => it.name !== idF && it.name !== 'id')
+    const required = items.filter((it: any) => !it.optional)
+    const chosen = required.length ? required : items.slice(0, 3)
+    const pairs = chosen.map((it: any) =>
+      `${it.name}: ${exampleValue(exampleEntity, primaryOpDef, it.name, 'example_' + it.name)}`)
+    return `{ ${pairs.join(', ')} }`
+  }
+  const testCallArg = primaryArg('test01')
+  const stateCallArg = primaryArg('example')
+  // Only read `.id` off the returned record when its data type carries one.
+  const stateDataLine = dataIdF
+    ? `console.log(data.${dataIdF})`
+    : `console.log(data)`
+
   const authActive = isAuthActive(model)
   const apikeyTesterCtor = authActive
     ? `new ${model.const.Name}SDK({ apikey: '...' })`
     : `new ${model.const.Name}SDK()`
   const apikeyExtendField = authActive ? `\n  apikey: '...',` : ''
-  const apikeyEnvLine = authActive ? `\n${model.NAME}_APIKEY=<your-key>` : ''
+  const apikeyEnvLine = authActive ? `\n${envName(model)}_APIKEY=<your-key>` : ''
 
   Content(`### Make a direct HTTP request
 
@@ -28,6 +71,9 @@ const result = await client.direct({
   params: { id: 'example' },
 })
 
+if (result instanceof Error) {
+  throw result
+}
 if (result.ok) {
   console.log(result.status)  // 200
   console.log(result.data)    // response body
@@ -56,9 +102,9 @@ Create a mock client for unit testing \u2014 no server required:
 \`\`\`ts
 const client = ${model.const.Name}SDK.test()
 
-const result = await client.Planet().load({ id: 'test01' })
-// result.ok === true
-// result.data contains mock response data
+const ${eVar} = await client.${eName}().${primaryOp}(${testCallArg})
+// ${eVar} is a bare entity populated with mock response data
+console.log(${eVar})
 \`\`\`
 
 You can also use the instance method:
@@ -73,14 +119,14 @@ const testClient = client.tester()
 Entity instances remember their last match and data:
 
 \`\`\`ts
-const entity = client.Planet()
+const entity = client.${eName}()
 
-// First call sets internal match
-await entity.load({ id: 'example' })
+// First call runs the operation and stores its result
+await entity.${primaryOp}(${stateCallArg})
 
-// Subsequent calls reuse the stored match
+// Subsequent calls reuse the stored state
 const data = entity.data()
-console.log(data.id) // 'example'
+${stateDataLine}
 \`\`\`
 
 ### Add custom middleware
@@ -109,7 +155,7 @@ const client = new ${model.const.Name}SDK({${apikeyExtendField}
 Create a \`.env.local\` file at the project root:
 
 \`\`\`
-${model.NAME}_TEST_LIVE=TRUE${apikeyEnvLine}
+${envName(model)}_TEST_LIVE=TRUE${apikeyEnvLine}
 \`\`\`
 
 Then run: