@voxgig/sdkgen 4.9.0 → 4.10.0

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

@@ -1,120 +0,0 @@
-import {
-  cmp, each,
-  File, Content, Copy, Folder,
-} from '@voxgig/sdkgen'
-
-import type {
-  ModelEntity
-} from '@voxgig/apidef'
-
-import {
-  KIT,
-  getModelPath
-} from '@voxgig/apidef'
-
-import { Package } from './Package_lean'
-import { Config } from './Config_lean'
-import { Gitignore } from './Gitignore_lean'
-
-
-// Op name -> generated wrapper. list/load/remove take a match; create takes
-// data; update takes both. Any non-standard op falls back to the match+data
-// form. Every wrapper delegates to the config-driven SdkRuntime.
-function opWrapper(entName: string, opName: string): string {
-  const q = `"${entName}"`
-  switch (opName) {
-    case 'list':
-      return `  def list (c m co : Value) : SIO Value := SdkRuntime.opList c ${q} m co\n`
-    case 'load':
-      return `  def load (c m co : Value) : SIO Value := SdkRuntime.opLoad c ${q} m co\n`
-    case 'remove':
-      return `  def remove (c m co : Value) : SIO Value := SdkRuntime.opRemove c ${q} m co\n`
-    case 'create':
-      return `  def create (c d co : Value) : SIO Value := SdkRuntime.opCreate c ${q} d co\n`
-    case 'update':
-      return `  def update (c m d co : Value) : SIO Value := SdkRuntime.opUpdate c ${q} m d co\n`
-    default:
-      return `  def ${opName} (c m d co : Value) : SIO Value := SdkRuntime.runOp c ${q} "${opName}" m d co\n`
-  }
-}
-
-
-const Main = cmp(async function Main(props: any) {
-
-  const { target } = props
-  const { model } = props.ctx$
-
-  const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
-
-  Package({ target })
-  Gitignore({})
-
-  // Copy tm/lean verbatim (placeholder substitution applies): the runtime under
-  // src/ (VoxgigStruct, Vregex, SdkJson, SdkRuntime), plus LICENSE/VERSION. The
-  // per-feature custom-source scaffold under src/feature is excluded.
-  Copy({
-    from: 'tm/' + target.name,
-    exclude: [/src\/feature\//],
-    replace: {
-      ...props.ctx$.stdrep,
-    }
-  })
-
-  // Generated modules under src/: the embedded API config and the public
-  // client (constructors + one op namespace per entity).
-  Folder({ name: 'src' }, () => {
-
-    Config({ target })
-
-    File({ name: 'SdkClient.' + target.ext }, () => {
-
-      let namespaces = ''
-      each(entity, (e: any) => {
-        // Capitalise the entity name for its op namespace.
-        const ns = e.name.charAt(0).toUpperCase() + e.name.slice(1)
-        let ops = ''
-        each(e.op, (op: any) => { ops += opWrapper(e.name, op.name) })
-        namespaces += `namespace ${ns}\n${ops}end ${ns}\n\n`
-      })
-
-      Content(`-- ${model.const.Name} SDK public client (generated by @voxgig/sdkgen).
---
--- Constructors (newSdk / testSdk) and one op namespace per entity. Entities are
--- generic: every op delegates to the config-driven SdkRuntime, so the pipeline
--- is identical for every entity and every API.
-
-import VoxgigStruct
-import SdkRuntime
-import SdkConfig
-
-open VoxgigStruct
-
-namespace Sdk
-
-/-- Construct a live client from an options map (empty map = defaults). -/
-def newSdk (options : Value) : SIO Value :=
-  SdkRuntime.mkClientV options SdkConfig.configJson
-
-/-- No-argument convenience constructor. -/
-def newSdk0 : SIO Value := do newSdk (← emptyMap)
-
-/-- Construct a test-mode client: operations are answered from an in-memory
-    store seeded with the entity test data, so no server is needed. -/
-def testSdk (seed : Value) (options : Value) : SIO Value :=
-  SdkRuntime.mkTestClientV options SdkConfig.configJson seed
-
-/-- Test client with default options. -/
-def testSdk0 (seed : Value) : SIO Value := do testSdk seed (← emptyMap)
-
-end Sdk
-
-${namespaces}`)
-    })
-  })
-
-})
-
-
-export {
-  Main
-}

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

@@ -1,93 +0,0 @@
-import {
-  Content,
-  File,
-  cmp,
-  packageVersion,
-} from '@voxgig/sdkgen'
-
-import type {
-  Model,
-} from '@voxgig/apidef'
-
-import { pkgName } from './utility_lean'
-
-
-// Each runtime module is its own `lean_lib` (Lake globs `<LibName>.lean` from
-// srcDir), matching the vendored struct project's layout. The runtime is
-// dependency-free (prelude + Std only); the HTTP transport shells to curl.
-const LIBS = [
-  'Vregex', 'VoxgigStruct', 'SdkJson', 'SdkUtility', 'SdkFeature', 'SdkFeatures', 'SdkRuntime', 'SdkConfig',
-  'SdkClient',
-]
-
-
-const Package = cmp(async function Package(props: any) {
-  const ctx$ = props.ctx$
-  const target = props.target
-  const model: Model = ctx$.model
-
-  const libBlocks = LIBS.map((n) =>
-    `[[lean_lib]]\nname = "${n}"\nsrcDir = "src"\n`).join('\n')
-
-  File({ name: 'lakefile.toml' }, () => {
-    Content(`# ${model.const.Name} SDK for Lean 4 (generated by @voxgig/sdkgen).
-name = "${pkgName(model)}"
-version = "${packageVersion(model, target.name)}"
-defaultTargets = ["SdkClient"]
-
-${libBlocks}
-# The corpus ENGINE: the vendored @voxgig/omni Lean port, source rather than
-# a dependency. Its own lean_lib so Lake can find the module, and
-# deliberately NOT in defaultTargets: only the test executables import it, so
-# \`lake build\` compiles the shipped library without it and nothing a
-# consumer installs ever names omni. Lake has no test-scoped dependency, so
-# vendoring is what keeps that isolation.
-[[lean_lib]]
-name = "Omni"
-srcDir = "test/vendor/omni"
-
-# The adapter that drives omni's native API with subjects built from this
-# SDK's own utilities. Imported by the corpus suites and the smoke test.
-[[lean_lib]]
-name = "OmniResolver"
-srcDir = "test"
-
-[[lean_exe]]
-name = "runner"
-srcDir = "test"
-root = "Runner"
-
-[[lean_exe]]
-name = "structcorpus"
-srcDir = "test"
-root = "StructCorpus"
-
-[[lean_exe]]
-name = "primary"
-srcDir = "test"
-root = "TPrimaryUtility"
-
-[[lean_exe]]
-name = "feature"
-srcDir = "test"
-root = "TFeature"
-
-# Smoke test for the vendored engine itself: a runner that cannot FAIL a bad
-# entry would turn every corpus suite vacuously green.
-[[lean_exe]]
-name = "omnismoke"
-srcDir = "test"
-root = "OmniSmoke"
-`)
-  })
-
-  // Pin the toolchain to the version the runtime is developed against.
-  File({ name: 'lean-toolchain' }, () => {
-    Content(`leanprover/lean4:v4.32.1\n`)
-  })
-})
-
-
-export {
-  Package
-}

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

@@ -1,29 +0,0 @@
-import { cmp, Content, each } from '@voxgig/sdkgen'
-
-// One section per entity: its op namespace and the verbs it supports.
-const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
-  const { entity } = props
-  if (null == entity) return
-  const ns = entity.name.charAt(0).toUpperCase() + entity.name.slice(1)
-  const ops = Object.keys(entity.op || {}).sort()
-  if (0 === ops.length) return
-
-  let rows = ''
-  for (const op of ops) {
-    const call =
-      'create' === op ? `${ns}.create sdk data (← emptyMap)`
-        : 'update' === op ? `${ns}.update sdk match data (← emptyMap)`
-          : `${ns}.${op} sdk match (← emptyMap)`
-    rows += `| \`${op}\` | \`${call}\` |\n`
-  }
-
-  Content(`Operations are in the \`${ns}\` namespace; each takes the client first
-and per-call options last.
-
-| Op | Call |
-| --- | --- |
-${rows}
-`)
-})
-
-export { ReadmeEntity }

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

@@ -1,19 +0,0 @@
-import { cmp, Content } from '@voxgig/sdkgen'
-
-const ReadmeExplanation = cmp(function ReadmeExplanation(_props: any) {
-  Content(`The SDK is **config-driven**: the API model is embedded as JSON in
-\`SdkConfig.lean\` and parsed into a \`Value\` when a client is constructed. An
-operation looks up its entity and op in that model, selects the matching
-endpoint (a point whose \`select.exist\` keys are satisfied), builds the URL from
-the point's path parts, applies the request transform, performs the call, then
-applies the response transform. Because the pipeline is data-driven rather than
-generated per entity, every entity and every API follow exactly the same path.
-
-The HTTP transport shells out to \`curl\` via \`IO.Process\` — Lean 4 has no HTTP
-library in its standard distribution, and this keeps the package free of Lake
-dependencies.
-
-`)
-})
-
-export { ReadmeExplanation }

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

@@ -1,25 +0,0 @@
-import { cmp, Content } from '@voxgig/sdkgen'
-
-const ReadmeHowto = cmp(function ReadmeHowto(_props: any) {
-  Content(`**Handle a missing record.** A \`load\` that finds nothing yields a
-non-map value, so match on it:
-
-\`\`\`lean
-match (← Entity.load sdk m (← emptyMap)) with
-| .map _ => IO.println "found"
-| _ => IO.println "not found"
-\`\`\`
-
-**Test without a server.** \`Sdk.testSdk0\` takes seed data (the shape of the
-generated \`<Entity>TestData.json\`) and answers operations from an in-memory
-store, so entity behaviour can be exercised offline:
-
-\`\`\`lean
-let seed ← SdkJson.jsonRead (← IO.FS.readFile "../.sdk/test/entity/<e>/<E>TestData.json")
-let sdk ← Sdk.testSdk0 seed
-\`\`\`
-
-`)
-})
-
-export { ReadmeHowto }

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

@@ -1,39 +0,0 @@
-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(`\`\`\`bash
-cd ${target.name} && lake build
-\`\`\`
-
-`)
-    return
-  }
-
-  const { releasesUrl } = repoInfo(model)
-  Content(`This package is not yet published to [Reservoir](https://reservoir.lean-lang.org).
-Install it from the GitHub release tag (\`${target.name}/vX.Y.Z\`, see
-[Releases](${releasesUrl})) or from a source checkout. The runtime is
-dependency-free (only the Lean 4 prelude + Std; the HTTP transport shells out
-to \`curl\`), so a plain Lake build is all that is needed:
-
-\`\`\`bash
-cd ${target.name} && lake build
-\`\`\`
-
-Run the offline struct-corpus test (no server needed) and the live entity
-tests (point them at a server with \`SDK_TEST_BASE\`):
-
-\`\`\`bash
-lake exe omnismoke
-lake exe structcorpus
-SDK_TEST_BASE=http://localhost:8901 lake exe runner
-\`\`\`
-
-`)
-})
-
-export { ReadmeInstall }

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

@@ -1,25 +0,0 @@
-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
-for Lean 4. The API is surfaced as capitalised Entities with a small, uniform
-verb set (\`list\`, \`load\`, \`create\`, \`update\`, \`remove\`); every operation is
-driven by the embedded config through the dependency-free vendored voxgig
-\`Value\` struct model, and runs in struct's \`SIO\` monad.
-
-`)
-
-  // touch the model so a mis-shaped model surfaces here, not at render time.
-  getModelPath(model, `main.${KIT}.entity`)
-})
-
-export { ReadmeIntro }

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

@@ -1,24 +0,0 @@
-import { cmp, Content } from '@voxgig/sdkgen'
-
-const ReadmeModel = cmp(function ReadmeModel(_props: any) {
-  Content(`Every value crossing the SDK boundary — options, request payloads,
-responses and results — is a vendored voxgig \`Value\` (see \`VoxgigStruct.lean\`):
-a JSON-shaped, heap-backed node, the Lean equivalent of the \`map[string]any\`
-the Go and Python SDKs pass around. Operations run in struct's \`SIO\` monad
-(\`ReaderT Ctx IO\`), so a single \`mkCtx\` is threaded through a run:
-
-\`\`\`lean
-let ctx ← mkCtx
-(do
-  let sdk ← Sdk.newSdk (← emptyMap)
-  ...
-).run ctx
-\`\`\`
-
-Build values with \`newMap\` / \`newList\`, read them with \`getprop\` / \`getpath\`,
-and render them with \`stringify\` (debug) or \`jsonify\` (strict JSON).
-
-`)
-})
-
-export { ReadmeModel }

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

@@ -1,22 +0,0 @@
-import { cmp, Content } from '@voxgig/sdkgen'
-
-const ReadmeOptions = cmp(function ReadmeOptions(_props: any) {
-  Content(`Options are a struct \`Value\` map passed to \`Sdk.newSdk\`:
-
-| Option | Meaning |
-| --- | --- |
-| \`base\` | API base URL (overrides the built-in default) |
-| \`prefix\` / \`suffix\` | Path fragments wrapped around every request path |
-| \`headers\` | Default request headers (merged with per-request headers) |
-| \`apikey\` | Bearer/api key, sent via the \`authorization\` header |
-| \`entity\` | Per-entity option overrides, keyed by entity name |
-
-\`\`\`lean
-let opts ← newMap #[("base", .str "https://api.example.com"), ("apikey", .str key)]
-let sdk ← Sdk.newSdk opts
-\`\`\`
-
-`)
-})
-
-export { ReadmeOptions }

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

@@ -1,50 +0,0 @@
-import { cmp, Content, isAuthActive, envName } from '@voxgig/sdkgen'
-import { KIT, getModelPath } from '@voxgig/apidef'
-
-// A capitalised entity op namespace + a representative read op for the example.
-function pickEntity(model: any): { ns: string, op: string } | null {
-  const entity = getModelPath(model, `main.${KIT}.entity`)
-  const ents = Object.values(entity || {}).filter((e: any) => e.active !== false)
-  for (const e of ents as any[]) {
-    const ops = Object.keys(e.op || {})
-    const op = ops.includes('list') ? 'list' : ops[0]
-    if (op) {
-      return { ns: e.name.charAt(0).toUpperCase() + e.name.slice(1), op }
-    }
-  }
-  return null
-}
-
-const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
-  const { ctx$: { model } } = props
-  const pick = pickEntity(model)
-  const ns = pick ? pick.ns : 'Entity'
-  const op = pick ? pick.op : 'list'
-  const auth = isAuthActive(model)
-  const optLines = [`("base", .str "https://api.example.com")`]
-  if (auth) {
-    optLines.push(`("apikey", .str (← IO.getEnv "${envName(model)}").getD "")`)
-  }
-
-  Content(`Construct a client with \`Sdk.newSdk\` and call an entity op. Everything runs
-in struct's \`SIO\` monad, so wrap your calls and \`.run\` them on a fresh \`mkCtx\`:
-
-\`\`\`lean
-import SdkClient
-
-open VoxgigStruct
-
-def main : IO Unit := do
-  let ctx ← mkCtx
-  (do
-    let opts ← newMap #[${optLines.join(', ')}]
-    let sdk ← Sdk.newSdk opts
-    let result ← ${ns}.${op} sdk (← emptyMap) (← emptyMap)
-    IO.println s!"result: {← stringify result}"
-  ).run ctx
-\`\`\`
-
-`)
-})
-
-export { ReadmeQuick }

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

@@ -1,40 +0,0 @@
-import { cmp, Content, File, ReadmeRefFeatures } from '@voxgig/sdkgen'
-
-
-// Lean emitted no REFERENCE.md at all. Every other per-language ReadmeRef
-// opens the File itself; this one only called Content(), so its module table
-// was written into no file and dropped, and lean was the one target shipping
-// no reference. Opening the File fixes that and gives the shared feature
-// reference somewhere to land.
-const ReadmeRef = cmp(function ReadmeRef(props: any) {
-  const { target, ctx$ } = props
-  const { model } = ctx$
-
-  File({ name: 'REFERENCE.md' }, () => {
-
-    Content(`# ${model.Name} ${target.title} SDK Reference
-
-Complete API reference for the ${model.Name} ${target.title} SDK.
-
-
-## Modules
-
-| Module | Purpose |
-| --- | --- |
-| \`SdkClient\` | \`Sdk.newSdk\` / \`Sdk.testSdk\` and the per-entity op namespaces |
-| \`SdkConfig\` | the embedded API model (JSON) |
-| \`SdkRuntime\` | the config-driven operation pipeline and curl transport |
-| \`SdkUtility\` | request-shaping utilities (spec, url, params, transforms, result) |
-| \`SdkJson\` | JSON text to struct \`Value\` |
-| \`VoxgigStruct\` | the vendored voxgig struct value model |
-
-
-## Features
-
-`)
-
-    ReadmeRefFeatures({ target })
-  })
-})
-
-export { ReadmeRef }

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

@@ -1,16 +0,0 @@
-import { cmp, Content } from '@voxgig/sdkgen'
-
-// The Lean stanza of the top-level README how-to section.
-const ReadmeTopHowto = cmp(function ReadmeTopHowto(props: any) {
-  const { target } = props
-  Content(`For Lean, point the client at another server with the \`base\` option,
-and run the entity suite against it with \`SDK_TEST_BASE\`:
-
-\`\`\`bash
-cd ${target.name} && SDK_TEST_BASE=http://localhost:8901 lake exe runner
-\`\`\`
-
-`)
-})
-
-export { ReadmeTopHowto }

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

@@ -1,23 +0,0 @@
-import { cmp, Content } from '@voxgig/sdkgen'
-
-// The Lean stanza of the top-level (multi-language) README quick start.
-const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
-  const { target } = props
-  Content(`\`\`\`lean
-import SdkClient
-open VoxgigStruct
-
-def main : IO Unit := do
-  let ctx ← mkCtx
-  (do
-    let sdk ← Sdk.newSdk (← emptyMap)
-    IO.println s!"client ready"
-  ).run ctx
-\`\`\`
-
-Build it with \`cd ${target.name} && lake build\`.
-
-`)
-})
-
-export { ReadmeTopQuick }

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

@@ -1,19 +0,0 @@
-import { cmp, Content } from '@voxgig/sdkgen'
-
-// The Lean stanza of the top-level README test section.
-const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
-  const { target } = props
-  Content(`\`\`\`bash
-cd ${target.name}
-lake build
-lake exe omnismoke      # the vendored @voxgig/omni corpus engine itself
-lake exe primary        # shared corpus: request-shaping utilities
-lake exe feature        # the feature catalog (retry, cache, rbac, netsim, …)
-lake exe structcorpus   # shared corpus: the vendored struct model
-lake exe runner         # entity behaviour (offline; add SDK_TEST_BASE for live)
-\`\`\`
-
-`)
-})
-
-export { ReadmeTopTest }