@voxgig/sdkgen 1.3.14 → 1.3.18

package/project/.sdk/src/cmp/swift/ReadmeEntity_swift.ts

@@ -0,0 +1,176 @@
+
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { swiftVarName } from './utility_swift'
+
+
+// Type names come from the shared canonToType 'swift' column (single source of truth).
+
+// A type-correct Swift `Value` literal for a field's canonical type.
+function swiftLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k) return '.int(1)'
+  if ('NUMBER' === k) return '.double(1.0)'
+  if ('BOOLEAN' === k) return '.bool(true)'
+  if ('ARRAY' === k) return '.list([])'
+  if ('OBJECT' === k) return '.map(VMap())'
+  return `.string("${placeholder}")`
+}
+
+
+// Operation method spelling for Swift: methods over the loose object model,
+// taking optional (reqmatch/reqdata, ctrl) and throwing on error. The op
+// descriptions are language-agnostic.
+const OP_DESC: Record<string, { method: string, desc: string }> = {
+  load:   { method: 'load(match, nil)',   desc: 'Load a single entity by match criteria.' },
+  list:   { method: 'list(nil, nil)',     desc: 'List entities, optionally matching the given criteria.' },
+  create: { method: 'create(data, nil)',  desc: 'Create a new entity with the given data.' },
+  update: { method: 'update(data, nil)',  desc: 'Update an existing entity.' },
+  remove: { method: 'remove(match, nil)', desc: 'Remove the matching entity.' },
+}
+
+
+const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const publishedEntities = each(entity)
+    .filter((entity: any) => entity.active !== false)
+
+  if (0 === publishedEntities.length) {
+    return
+  }
+
+  Content(`
+
+## Entities
+
+`)
+
+  publishedEntities.map((entity: any) => {
+    const opnames = Object.keys(entity.op || {})
+    const fields = entity.fields || []
+    // Model-driven id key: null when this entity has no id-like field.
+    const idF = entityIdField(entity)
+    // Sanitise the local variable name — a camelCased Swift keyword gets a
+    // trailing underscore (swiftVarName) so the snippet compiles.
+    const eVar = swiftVarName(entity.name)
+    const accessor = entity.Name
+
+    Content(`
+### ${entity.Name}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create an instance: \`let ${eVar} = client.${accessor}()\`
+
+`)
+
+    if (opnames.length > 0) {
+      Content(`#### Operations
+
+| Method | Description |
+| --- | --- |
+`)
+      opnames.map((opname: string) => {
+        const info = OP_DESC[opname]
+        if (info) {
+          Content(`| \`${info.method}\` | ${info.desc} |
+`)
+        }
+      })
+
+      Content(`
+`)
+    }
+
+    if (fields.length > 0) {
+      Content(`#### Fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+`)
+
+      each(fields, (field: any) => {
+        const desc = field.short || ''
+        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
+`)
+      })
+
+      Content(`
+`)
+    }
+
+    if (opnames.includes('load')) {
+      // The id key plus every REQUIRED match key (parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      const loadItems = opRequestShape(entity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `VMap([${loadItems.map((it: any) =>
+          `("${it.name}", ${swiftLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)})`).join(', ')}])`
+        : 'nil'
+      Content(`#### Example: Load
+
+\`\`\`swift
+let ${eVar} = try client.${accessor}().load(${loadArg}, nil)
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`#### Example: List
+
+\`\`\`swift
+let ${eVar}List = try client.${accessor}().list(nil, nil)
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('create')) {
+      // Members come from the SAME shape the runtime validates
+      // (opRequestShape): every required member must appear — including a
+      // required id and parent keys like page_id — with a real literal.
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
+      Content(`#### Example: Create
+
+\`\`\`swift
+let ${eVar} = try client.${accessor}().create(VMap([
+`)
+      createItems.map((it: any, i: number) => {
+        const comma = i < createItems.length - 1 ? ',' : ''
+        Content(`    ("${it.name}", ${swiftLit(it.type, 'example_' + it.name)})${comma}  // ${canonToType(it.type, target.name)}
+`)
+      })
+      Content(`]), nil)
+\`\`\`
+
+`)
+    }
+  })
+})
+
+
+export {
+  ReadmeEntity
+}

package/project/.sdk/src/cmp/swift/ReadmeExamplesTest_swift.ts

@@ -0,0 +1,187 @@
+
+import { cmp, File, Content } from '@voxgig/sdkgen'
+
+
+// Emits Tests/ProjectNameSDKTests/ReadmeExamplesTest.swift — a PRESENCE +
+// STRUCTURE gate over every swift fenced block in the repository ROOT
+// README.md, the per-language swift/README.md, AND swift/REFERENCE.md. It is a
+// plain XCTestCase (no @testable import — it only reads the doc files off
+// disk), resolved relative to the test file via #filePath.
+//
+// SCOPE NOTE (deliberate, documented): the Python/TS/Go equivalents EXECUTE and
+// type-check every documented block. That is infeasible here — the generated
+// Swift SDK compiles with SwiftPM only (no in-process Swift compiler wired into
+// the test runtime), so a test cannot compile-and-run arbitrary doc snippets at
+// test time. This gate therefore guarantees the weaker-but-real invariant that
+// keeps the docs honest as the generator evolves:
+//   1. PRESENCE: every scanned doc that exists holds at least one swift block
+//      (nothing was dropped);
+//   2. STRUCTURE: every swift block's braces / parens / brackets balance
+//      (ignoring string literals and line comments), catching a truncated or
+//      malformed generated snippet.
+//
+// The emitted Swift is written WITHOUT literal backticks (the fence marker is
+// built at runtime as String(repeating: "\u{60}", count: 3)) so this TS
+// template literal stays clean, and uses string concatenation instead of Swift
+// interpolation to keep backslash-escaping in this template minimal.
+const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
+  const { ctx$: { model } } = props
+
+  const Name = model.const.Name
+
+  File({ name: 'ReadmeExamplesTest.swift' }, () => {
+    Content(`// ${Name} SDK — documentation swift-examples PRESENCE + STRUCTURE gate.
+//
+// GUARANTEE (see ReadmeExamplesTest_swift.ts for why this is a structure gate
+// and not an execute gate): every swift example in the docs is accounted for.
+// A dependency-free XCTestCase over every swift fenced code block in three
+// documents:
+//   - the repository ROOT README.md (one directory above the swift module),
+//   - the per-language swift/README.md,
+//   - the per-language swift/REFERENCE.md.
+//
+// Checks, PER DOCUMENT that exists:
+//   1. PRESENCE: the doc holds at least one swift block.
+//   2. STRUCTURE: every swift block's braces / parens / brackets balance, so a
+//      truncated or malformed generated snippet fails loudly. An unclosed fence
+//      (odd number of fence markers) also fails, rather than silently absorbing
+//      the trailing text as a block.
+//
+// GENERATED by @voxgig/sdkgen — do not edit by hand.
+
+import XCTest
+import Foundation
+
+final class ReadmeExamplesTest: XCTestCase {
+  private struct Doc { let label: String; let path: String }
+
+  private let NL: Character = "\\n"
+
+  // The triple-backtick fence, built at runtime so this source carries no
+  // literal backticks.
+  private var fence: String { String(repeating: "\\u{60}", count: 3) }
+
+  // The three documents to scan, resolved relative to this test file.
+  private func docs() -> [Doc] {
+    let here = URL(fileURLWithPath: #filePath)
+      .deletingLastPathComponent()   // ProjectNameSDKTests
+      .deletingLastPathComponent()   // Tests
+      .deletingLastPathComponent()   // swift (module dir)
+    let project = here.deletingLastPathComponent()  // project (holds root README)
+    return [
+      Doc(label: "root README", path: project.appendingPathComponent("README.md").path),
+      Doc(label: "swift README.md", path: here.appendingPathComponent("README.md").path),
+      Doc(label: "swift REFERENCE.md", path: here.appendingPathComponent("REFERENCE.md").path),
+    ]
+  }
+
+  // Extract every swift fenced block. Split on the triple-backtick fence:
+  // odd-indexed segments are the inside of a fenced block (info string on the
+  // first line, then the code). Only blocks whose info string is exactly
+  // "swift" are returned.
+  private func swiftBlocks(_ text: String) -> [String] {
+    let parts = text.components(separatedBy: fence)
+    var blocks: [String] = []
+    var i = 1
+    while i < parts.count {
+      let seg = parts[i]
+      let split = seg.split(separator: NL, maxSplits: 1, omittingEmptySubsequences: false)
+      let first = split.first.map { String($0) } ?? ""
+      let info = first.trimmingCharacters(in: .whitespaces)
+      if info == "swift" {
+        blocks.append(split.count > 1 ? String(split[1]) : "")
+      }
+      i += 2
+    }
+    return blocks
+  }
+
+  // True when the doc has a fence that was opened but never closed. A
+  // well-formed doc holds fence markers in open/close pairs, so an ODD number
+  // of markers means the final fence dangles — the split-based scan above would
+  // otherwise silently treat the truncated tail as a block. This is the
+  // structural analogue of an at-EOF "still inside a block" check.
+  private func hasUnclosedFence(_ text: String) -> Bool {
+    let fenceCount = text.components(separatedBy: fence).count - 1
+    return fenceCount % 2 != 0
+  }
+
+  // True when every open/close delimiter balances, ignoring characters inside
+  // string literals and line comments (a generated snippet never nests an
+  // unbalanced delimiter outside those, and this catches truncation).
+  private func balanced(_ block: String) -> Bool {
+    var stack: [Character] = []
+    var inString = false
+    var escaped = false
+    let chars = Array(block)
+    var i = 0
+    while i < chars.count {
+      let ch = chars[i]
+      if inString {
+        if escaped { escaped = false }
+        else if ch == "\\\\" { escaped = true }
+        else if ch == "\\"" { inString = false }
+        i += 1
+        continue
+      }
+      if ch == "\\"" { inString = true; i += 1; continue }
+      if ch == "/" && i + 1 < chars.count && chars[i + 1] == "/" {
+        while i < chars.count && chars[i] != NL { i += 1 }
+        continue
+      }
+      switch ch {
+      case "(": stack.append(")")
+      case "[": stack.append("]")
+      case "{": stack.append("}")
+      case ")", "]", "}":
+        if stack.isEmpty || stack.removeLast() != ch { return false }
+      default: break
+      }
+      i += 1
+    }
+    return stack.isEmpty && !inString
+  }
+
+  private func read(_ path: String) -> String? {
+    return try? String(contentsOfFile: path, encoding: .utf8)
+  }
+
+  // PRESENCE: each doc that exists holds at least one swift block.
+  func testDocExamplesPresent() {
+    for doc in docs() {
+      guard let text = read(doc.path) else { continue }
+      let blocks = swiftBlocks(text)
+      XCTAssertGreaterThan(blocks.count, 0,
+        "expected at least one swift block in " + doc.label)
+    }
+  }
+
+  // STRUCTURE: every swift block's delimiters balance.
+  func testDocExamplesWellFormed() {
+    var failures: [String] = []
+    for doc in docs() {
+      guard let text = read(doc.path) else { continue }
+      // A fence opened but never closed is a malformed doc — fail loudly rather
+      // than silently absorbing the unterminated tail as a block.
+      if hasUnclosedFence(text) {
+        failures.append(doc.label + " has an unclosed swift code fence")
+      }
+      let blocks = swiftBlocks(text)
+      var balancedCount = 0
+      for (i, b) in blocks.enumerated() {
+        if balanced(b) { balancedCount += 1 }
+        else { failures.append(doc.label + " swift block #" + String(i) + " has unbalanced delimiters") }
+      }
+      print("[readme-examples] " + doc.label + " swift blocks: total=" + String(blocks.count) + " balanced=" + String(balancedCount))
+    }
+    XCTAssertTrue(failures.isEmpty, failures.joined(separator: "; "))
+  }
+}
+`)
+  })
+})
+
+
+export {
+  ReadmeExamplesTest
+}

package/project/.sdk/src/cmp/swift/ReadmeExplanation_swift.ts

@@ -0,0 +1,49 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const SDK = model.const.Name + 'SDK'
+
+  Content(`### Data as loose values
+
+The Swift SDK uses a loose object model — the vendored \`Value\` enum
+(with \`VMap\` / \`VList\` wrappers) throughout — rather than a bespoke typed
+struct per endpoint. This mirrors the dynamic nature of the API and keeps the
+SDK flexible: no regeneration is needed when the API schema changes.
+
+Use the \`.asMap\` / \`.asList\` / \`.asString\` accessors to safely coerce a
+\`Value\` to a concrete Swift type (each returns \`nil\` on a type mismatch).
+A \`${model.const.Name}Types.swift\` file of reference \`struct\` types is also
+generated for editor documentation.
+
+### Project structure
+
+\`\`\`
+swift/
+├── Package.swift                     -- SwiftPM manifest (zero runtime deps)
+├── Sources/ProjectNameSDK/
+│   ├── core/                         -- Main client, config, entity base, error type
+│   ├── entity/                       -- Generated entity clients
+│   ├── feature/                      -- Built-in features (Base, Test, Log, ...)
+│   ├── utility/                      -- Utility functions
+│   └── Struct/                       -- Vendored Voxgig Struct port
+└── Tests/ProjectNameSDKTests/        -- Test suites (XCTest)
+\`\`\`
+
+The main client class (\`${SDK}\`, under \`Sources/ProjectNameSDK/core\`)
+exposes the entity accessors. Reference entity or utility types directly only
+when needed. The SDK is dependency-free: JSON parsing is the vendored
+\`Struct/JSON.swift\`, HTTP transport is Foundation's \`URLSession\`, and the
+struct library is inlined under \`Struct/\`.
+
+`)
+
+})
+
+
+export {
+  ReadmeExplanation
+}

package/project/.sdk/src/cmp/swift/ReadmeHowto_swift.ts

@@ -0,0 +1,159 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { swiftVarName } from './utility_swift'
+
+
+// A type-correct Swift `Value` literal for a field's canonical type.
+function swiftLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k) return '.int(1)'
+  if ('NUMBER' === k) return '.double(1.0)'
+  if ('BOOLEAN' === k) return '.bool(true)'
+  if ('ARRAY' === k) return '.list([])'
+  if ('OBJECT' === k) return '.map(VMap())'
+  return '.string("example")'
+}
+
+
+const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const SDK = model.const.Name + 'SDK'
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  // Pick an entity with a real op (prefer a read op). primaryOp is null only
+  // when NO entity exposes any op (a direct()-only SDK).
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
+  const eName = exampleEntity ? exampleEntity.Name : 'Entity'
+  const eVar = exampleEntity ? swiftVarName(exampleEntity.name) : 'entity'
+  // Model-driven id key: null when the entity has no id-like field, so a
+  // match op takes an empty match.
+  const idF = exampleEntity ? entityIdField(exampleEntity) : null
+  const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+  let testArg = 'nil'
+  if (exampleEntity && isMatchOp) {
+    testArg = idF ? `VMap([("${idF}", .string("test01"))])` : 'nil'
+  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
+    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)
+    testArg = `VMap([${chosen.map((it: any) =>
+      `("${it.name}", ${swiftLit(it.type)})`).join(', ')}])`
+  }
+
+  // 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 bare record and throw on error.
+let ${eVar} = try client.${eName}().${primaryOp}(${testArg}, nil)
+// ${eVar} holds the mock response record
+print(${eVar})`
+    : `let result = client.direct(VMap([
+    ("path", .string("/api/resource")),
+    ("method", .string("GET")),
+]))
+print(result)`
+
+  const apikeyEnvLine = isAuthActive(model)
+    ? `\n${envName(model)}_APIKEY=<your-key>`
+    : ''
+
+  Content(`### Make a direct HTTP request
+
+For endpoints not covered by entity methods:
+
+\`\`\`swift
+let result = client.direct(VMap([
+    ("path", .string("/api/resource/{id}")),
+    ("method", .string("GET")),
+    ("params", .map([("id", .string("example"))])),
+]))
+
+if result.entries["ok"] == .bool(true) {
+    print(result.entries["status"] ?? .noval)  // 200
+    print(result.entries["data"] ?? .noval)     // response body
+}
+else {
+    // A non-2xx response carries status + data (the error body); a
+    // transport-level failure carries err instead. Only one is present, so
+    // an absent key simply reads as .noval.
+    print(result.entries["status"] ?? .noval, result.entries["err"] ?? .noval)
+}
+\`\`\`
+
+### Prepare a request without sending it
+
+\`\`\`swift
+// prepare() returns the fetch definition and throws on error.
+let fetchdef = try client.prepare(VMap([
+    ("path", .string("/api/resource/{id}")),
+    ("method", .string("DELETE")),
+    ("params", .map([("id", .string("example"))])),
+]))
+
+print(fetchdef.entries["url"] ?? .noval)
+print(fetchdef.entries["method"] ?? .noval)
+print(fetchdef.entries["headers"] ?? .noval)
+\`\`\`
+
+### Use test mode
+
+Create a mock client for unit testing — no server required:
+
+\`\`\`swift
+let client = ${SDK}.testSDK(nil, nil)
+
+${testModeExample}
+\`\`\`
+
+### Use a custom fetch function
+
+Replace the HTTP transport with your own \`SystemFetch\` closure:
+
+\`\`\`swift
+let fetch: SystemFetch = { url, _ in
+    let m = VMap()
+    m.entries["status"] = .int(200)
+    m.entries["statusText"] = .string("OK")
+    m.entries["headers"] = .map(VMap())
+    m.entries["json"] = .nat({ () -> Value in .map(VMap([("id", .string("mock01"))])) } as NativeCall0)
+    return .map(m)
+}
+
+let system = VMap()
+system.entries["fetch"] = .nat(fetch)
+let options = VMap()
+options.entries["base"] = .string("http://localhost:8080")
+options.entries["system"] = .map(system)
+let client = ${SDK}(options)
+\`\`\`
+
+### Run live tests
+
+Create a \`.env.local\` file at the project root:
+
+\`\`\`
+${envName(model)}_TEST_LIVE=TRUE${apikeyEnvLine}
+\`\`\`
+
+Then run:
+
+\`\`\`bash
+cd swift && make test
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeHowto
+}

package/project/.sdk/src/cmp/swift/ReadmeInstall_swift.ts

@@ -0,0 +1,58 @@
+
+import { cmp, Content, isPublished, repoInfo } from '@voxgig/sdkgen'
+
+
+const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
+  const { target, ctx$ } = props
+  const { model } = ctx$
+
+  if (isPublished(model, target.name)) {
+    Content(`Add the package as a dependency in your \`Package.swift\`:
+
+\`\`\`swift
+dependencies: [
+    .package(url: "<repo-url>", from: "0.0.1"),
+],
+\`\`\`
+
+Or build from a source checkout — the SDK is a plain SwiftPM package:
+
+\`\`\`bash
+cd swift && swift build
+\`\`\`
+
+`)
+    return
+  }
+
+  // Publish pending: not yet on the SwiftPM registry (git-tag only). The
+  // generated SDK is a dependency-free SwiftPM package (Foundation + the
+  // vendored Voxgig Struct port), so install it from the git release tag or a
+  // local source checkout and build with SwiftPM.
+  const { releasesUrl } = repoInfo(model)
+  Content(`This package is not yet published to a SwiftPM registry. The generated SDK
+is a dependency-free SwiftPM package (Foundation only, plus the vendored
+Voxgig Struct port). Depend on it from the GitHub release tag
+(\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})) by adding it to
+your \`Package.swift\`:
+
+\`\`\`swift
+dependencies: [
+    // From the git release tag:
+    .package(url: "<repo-url>", exact: "0.0.1"),
+],
+\`\`\`
+
+Or build from a source checkout with SwiftPM:
+
+\`\`\`bash
+cd swift && swift build
+\`\`\`
+
+`)
+})
+
+
+export {
+  ReadmeInstall
+}

package/project/.sdk/src/cmp/swift/ReadmeIntro_swift.ts

@@ -0,0 +1,64 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
+  const { target, ctx$: { model } } = props
+  const info = (model.main && model.main.kit && model.main.kit.info) || {}
+  const tagline = info.tagline || ''
+
+  Content(`# ${model.Name} ${target.title} SDK
+
+${tagline}
+
+The ${target.title} SDK for the ${model.Name} API — an entity-oriented client following idiomatic Swift conventions.
+
+`)
+
+  // Emphasise the entity-oriented design: the SDK surfaces the API as
+  // capitalised, semantic Entities with a small, uniform verb set rather
+  // than raw URL paths and query strings. The example entity name is
+  // derived from the model, never hardcoded.
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const exampleEntity = Object.values(entity || {})
+    .find((e: any) => e.active !== false) as any
+  const example = exampleEntity
+    ? `for example \`client.${exampleEntity.Name}()\` — each`
+    : 'each'
+
+  // Model-driven op list — only the operations the active entities actually
+  // expose (a read-only entity has just list+load); never claim
+  // create/update/remove exist when no entity has them.
+  const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
+  const opSet = new Set<string>()
+  Object.values(entity || {}).forEach((e: any) => {
+    if (!e || e.active === false) return
+    Object.keys(e.op || {}).forEach((o: string) => {
+      if (e.op[o] && e.op[o].active !== false) opSet.add(o)
+    })
+  })
+  const opNames = CANON_OPS.filter((o) => opSet.has(o))
+    .concat([...opSet].filter((o) => !CANON_OPS.includes(o)))
+  const opList = (opNames.length ? opNames : ['list', 'load'])
+    .map((o) => '`' + o + '`').join(', ')
+
+  Content(`The SDK exposes the API as capitalised, semantic **Entities** — ${example}
+carrying a small, uniform set of operations (${opList}) instead of raw URL
+paths and query strings. You work with named resources and verbs, which
+keeps the cognitive load low.
+
+> Other languages, the CLI, and MCP server live alongside this one — see
+> the [top-level README](../README.md).
+
+`)
+})
+
+
+export {
+  ReadmeIntro
+}