@voxgig/sdkgen 1.3.14 → 1.3.17

package/project/.sdk/src/cmp/go-mcp/Main_go-mcp.ts

@@ -70,58 +70,198 @@ const Main = cmp(function Main(props: any) {
 /go-mcp
 `))
 
-  // README.md — usage guide for the MCP server.
+  // ==========================================================================
+  // README.md — Diátaxis-structured, examples-first usage guide.
+  //
+  // The server ALWAYS registers exactly two tools (<slug>_list / <slug>_load;
+  // see tools.fragment.go), so tools are not gated. Concrete tool-call and
+  // entity examples are MODEL-DRIVEN off the real slug + entity names.
+  // ==========================================================================
+  const bin = `${model.name}-mcp`
+  const toolList = `${slugLower}_list`
+  const toolLoad = `${slugLower}_load`
+  const entityCount = entityNames.length
+  const entityNoun = entityCount === 1 ? 'entity' : 'entities'
   const firstEntity = entityNames[0] || 'entity'
+
+  // Example entities chosen per-op so a doc example never shows an entity that
+  // doesn't support the op being demonstrated (both tools are always
+  // registered, but a given entity only responds to the ops it exposes).
+  const activeEntityObjs: any[] =
+    Object.values(entityMap).filter((e: any) => e && e.active !== false)
+  const entWithOp = (op: string) => {
+    const e = activeEntityObjs.find(
+      (x: any) => x.op && x.op[op] && x.op[op].active !== false)
+    return e ? String(e.name).toLowerCase() : firstEntity
+  }
+  const listEntity = entWithOp('list')
+  const loadEntity = entWithOp('load')
+
+  const projUpper = String(model.name).toUpperCase().replace(/[^A-Z0-9]/g, '_')
+  const apiKeyEnv = projUpper + '_APIKEY'
+  const baseEnv = projUpper + '_BASE'
+
   File({ name: 'README.md' }, () => Content(`# ${model.name}-mcp
 
-MCP server exposing the ${model.Name} SDK as tools, built on the
-[official Go MCP SDK](https://github.com/modelcontextprotocol/go-sdk)
-and the sibling Go SDK at \`../go\`.
+[MCP](https://modelcontextprotocol.io) server exposing the ${model.Name} SDK as
+two agent tools — \`${toolList}\` and \`${toolLoad}\` — built on the
+[official Go MCP SDK](https://github.com/modelcontextprotocol/go-sdk) and the
+sibling Go SDK at \`../go\`. Runs over **stdio** (default, for spawnable installs)
+or **streamable HTTP** (one shared server for several agents).
 
-## Tools
+## Examples
 
-| Tool | Args | Returns |
-|------|------|---------|
-| \`${slugLower}_list\` | \`entity\`, optional \`query\` map | First page of records as JSON |
-| \`${slugLower}_load\` | \`entity\`, \`query\` (e.g. \`{id:N}\`) | Single record as JSON |
+\`\`\`sh
+# 1. Build a native binary (-> dist/<os>-<arch>/${bin})
+make build
 
-JSON schemas for both tools are emitted by the SDK from the \`Args\`
-struct's \`json\` / \`jsonschema\` tags — no schema is hand-written.
+# 2. Provide credentials via the environment
+export ${apiKeyEnv}=sk_live_xxx
 
-## Entities
+# 3a. Install into Claude Code over stdio (most common)
+claude mcp add --scope user ${slugLower} \\
+  -- /absolute/path/to/${bin} -transport stdio
 
-${entityHelp}
+# 3b. …or run a shared HTTP server instead
+./${bin} -transport http -addr :8080
+\`\`\`
+
+Tool-call arguments (what an agent sends):
+
+\`\`\`jsonc
+// ${toolList}: first page of records
+{ "entity": "${listEntity}" }
+{ "entity": "${listEntity}", "query": { } }
+
+// ${toolLoad}: one record by id
+{ "entity": "${loadEntity}", "query": { "id": 1 } }
+\`\`\`
+
+> The rest of this guide follows the [Diátaxis](https://diataxis.fr) framework:
+> a hands-on **Tutorial**, task-focused **How-to guides**, a factual
+> **Reference**, and background **Explanation**.
+
+## Tutorial: install and call a tool
+
+1. **Build** the server from this \`go-mcp/\` directory:
 
-## Build
+   \`\`\`sh
+   make build          # -> dist/<os>-<arch>/${bin}
+   \`\`\`
+
+2. **Set your API key:**
+
+   \`\`\`sh
+   export ${apiKeyEnv}=sk_live_xxx
+   \`\`\`
+
+3. **Install it into Claude Code** (stdio transport):
+
+   \`\`\`sh
+   claude mcp add --scope user ${slugLower} \\
+     -- "$PWD"/dist/*/${bin} -transport stdio
+   \`\`\`
+
+4. **Restart Claude Code.** The \`${toolList}\` and \`${toolLoad}\` tools now appear
+   in new sessions. Ask the agent to *"list ${listEntity} using ${slugLower}"*
+   and it calls \`${toolList}\` with \`{"entity":"${listEntity}"}\`.
+
+## How-to guides
+
+### Authenticate and choose an environment
+
+Configuration is read from the environment — nothing is written to disk:
 
 \`\`\`sh
-go build -o ${model.name}-mcp ./...
+export ${apiKeyEnv}=sk_live_xxx            # API key
+export ${baseEnv}=https://api.example.com  # optional: override the API base URL
 \`\`\`
 
-## Run
+Set these in the shell that launches the server (or in the \`claude mcp add\`
+environment) so every tool call is authenticated.
+
+### Run as a shared HTTP server
 
 \`\`\`sh
-# stdio transport — for spawnable agent installs (default).
-./${model.name}-mcp
+./${bin} -transport http -addr :8080
+\`\`\`
+
+Streamable HTTP lets several agents share one running process; stdio (the
+default) spawns a fresh process per client.
 
-# streamable HTTP transport — share one running server between agents.
-./${model.name}-mcp -transport http -addr :8080
+### Call the \`${toolList}\` tool
+
+Args: \`entity\` (required), \`query\` (optional filter map). Returns the first
+page of records as JSON:
+
+\`\`\`jsonc
+{ "entity": "${listEntity}" }
 \`\`\`
 
-## Install for Claude Code
+### Call the \`${toolLoad}\` tool
+
+Args: \`entity\` (required), \`query\` = \`{"id":N}\` (required). Returns the single
+record as JSON:
+
+\`\`\`jsonc
+{ "entity": "${loadEntity}", "query": { "id": 1 } }
+\`\`\`
+
+### Cross-compile release binaries
 
 \`\`\`sh
-claude mcp add --scope user ${slugLower} \\
-  -- /absolute/path/to/${model.name}-mcp -transport stdio
+make build       # native binary for this machine
+make build-all   # linux/darwin/windows x amd64/arm64, under dist/<os>-<arch>/
 \`\`\`
 
-After install, restart Claude Code; the \`${slugLower}_list\` and
-\`${slugLower}_load\` tools become available in new sessions.
+## Reference
+
+### Tools
+
+| Tool | Args | Returns |
+|------|------|---------|
+| \`${toolList}\` | \`entity\` (required), \`query\` (optional map) | First page of records as JSON |
+| \`${toolLoad}\` | \`entity\` (required), \`query\` = \`{id:N}\` | Single record as JSON |
+
+On error, a tool returns an MCP error result (\`isError: true\`) whose text is the
+failure message (e.g. unknown entity, or an API error).
+
+### \`Args\` schema
+
+Both tools take the same argument object:
+
+| Field | Type | Notes |
+|-------|------|-------|
+| \`entity\` | string | One of the ${entityCount} supported entities (see below). |
+| \`query\` | object | Optional match map. \`{"id":N}\` for load; omit or \`{}\` for list. |
+
+JSON schemas are emitted by the SDK from the \`Args\` struct's \`json\` /
+\`jsonschema\` tags — no schema is hand-written.
+
+### Transports & flags
 
-## Smoke test via HTTP
+| Flag | Default | Purpose |
+|------|---------|---------|
+| \`-transport\` | \`stdio\` | \`stdio\` (spawnable) or \`http\` (streamable HTTP). |
+| \`-addr\` | \`:8080\` | Listen address for the \`http\` transport. |
+
+### Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| \`${apiKeyEnv}\` | API key sent with every request. |
+| \`${baseEnv}\` | Optional override of the API base URL. |
+
+### Entities
+
+The ${entityCount} ${entityNoun} valid as the \`entity\` argument:
+
+${entityHelp}
+
+### Smoke test via HTTP (raw JSON-RPC)
 
 \`\`\`sh
-./${model.name}-mcp -transport http -addr :18080 &
+./${bin} -transport http -addr :18080 &
 
 # initialize, grab the session id
 curl -sN -X POST http://localhost:18080 \\
@@ -136,13 +276,34 @@ curl -sN -X POST http://localhost:18080 \\
   -H 'Content-Type: application/json' \\
   -H 'Accept: application/json, text/event-stream' \\
   -H "Mcp-Session-Id: $SESSION" \\
-  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"${slugLower}_load","arguments":{"entity":"${firstEntity}","query":{"id":1}}}}'
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"${toolLoad}","arguments":{"entity":"${loadEntity}","query":{"id":1}}}}'
 \`\`\`
 
+## Explanation
+
+### How tools map to the SDK
+
+\`main.go\` builds the SDK client (configured from the environment) and registers
+two tools. Each dispatches on the \`entity\` argument to the matching entity in
+the sibling Go SDK at \`../go\`, calls \`List\` or \`Load\`, unwraps the \`Entity\`
+wrappers to plain data, and returns it as pretty-printed JSON.
+
+### Why two transports
+
+**stdio** is the standard for agent hosts that spawn a server per client
+(Claude Code's \`claude mcp add\`). **streamable HTTP** keeps one process running
+that many agents can share — handy for a long-lived deployment.
+
+### Schema generation
+
+The input schema is derived from the \`Args\` Go struct's \`json\` / \`jsonschema\`
+tags at registration time, so the advertised tool schema can never drift from
+the code that consumes it.
+
 ## Generated by
 
-sdkgen \`go-mcp\` target. See the target source under
-\`.sdk/src/cmp/go-mcp/\` in this repo, or upstream at
+sdkgen \`go-mcp\` target. See the target source under \`.sdk/src/cmp/go-mcp/\` in
+this repo, or upstream at
 \`github.com/voxgig/sdkgen/project/.sdk/src/cmp/go-mcp/\`.
 `))
 

package/project/.sdk/src/cmp/haskell/ReadmeEntity_haskell.ts

@@ -0,0 +1,181 @@
+
+import { cmp, each, Content, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { hsVarName } from './utility_haskell'
+
+
+// A type-correct Haskell `Value` literal for a field's canonical type.
+function hsLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return 'VNum 1'
+  if ('BOOLEAN' === k) return 'VBool True'
+  if ('ARRAY' === k || 'OBJECT' === k) return 'VNoval'
+  return `VStr "${placeholder}"`
+}
+
+
+// A readable Haskell type name for a field's canonical type. The runtime
+// carries every field as a dynamic `Value`; this documents the logical type.
+function hsType(type: any): string {
+  const k = canonKey(type)
+  if ('STRING' === k) return 'String'
+  if ('INTEGER' === k) return 'Int'
+  if ('NUMBER' === k) return 'Double'
+  if ('BOOLEAN' === k) return 'Bool'
+  if ('ARRAY' === k) return '[Value]'
+  return 'Value'
+}
+
+
+const OP_DESC: Record<string, { method: string, desc: string }> = {
+  load:   { method: 'eLoad ent match ctrl',   desc: 'Load a single entity by match criteria.' },
+  list:   { method: 'eList ent match ctrl',   desc: 'List entities, optionally matching the given criteria.' },
+  create: { method: 'eCreate ent data ctrl',  desc: 'Create a new entity with the given data.' },
+  update: { method: 'eUpdate ent data ctrl',  desc: 'Update an existing entity.' },
+  remove: { method: 'eRemove ent match ctrl', 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 || []
+    const idF = entityIdField(entity)
+    const eFn = hsVarName(entity.name)
+
+    Content(`
+### ${entity.Name}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create an instance: \`${eFn} <- Sdk.${eFn} sdk VNoval\`
+
+`)
+
+    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}\` | \`${hsType(field.type)}\` | ${desc} |
+`)
+      })
+
+      Content(`
+`)
+    }
+
+    if (opnames.includes('load')) {
+      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
+        ? `[${loadItems.map((it: any) =>
+          `("${it.name}", ${hsLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)})`).join(', ')}]`
+        : '[]'
+      Content(`#### Example: Load
+
+\`\`\`haskell
+  ent <- Sdk.${eFn} sdk VNoval
+  match <- jo ${loadArg}
+  ctrl <- emptyMap
+  ${eFn} <- Sdk.eLoad ent match ctrl
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`#### Example: List
+
+\`\`\`haskell
+  ent <- Sdk.${eFn} sdk VNoval
+  match <- emptyMap
+  ctrl <- emptyMap
+  ${eFn}s <- Sdk.eList ent match ctrl
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('create')) {
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
+      Content(`#### Example: Create
+
+\`\`\`haskell
+  ent <- Sdk.${eFn} sdk VNoval
+  d <- jo
+    [`)
+      createItems.map((it: any, i: number) => {
+        const bracket = 0 === i ? ' ' : ', '
+        Content(`${bracket}("${it.name}", ${hsLit(it.type, 'example_' + it.name)})   -- ${hsType(it.type)}
+    `)
+      })
+      Content(`]
+  ctrl <- emptyMap
+  ${eFn} <- Sdk.eCreate ent d ctrl
+\`\`\`
+
+`)
+    }
+  })
+})
+
+
+export {
+  ReadmeEntity
+}

package/project/.sdk/src/cmp/haskell/ReadmeExamplesTest_haskell.ts

@@ -0,0 +1,125 @@
+
+import { cmp, File, Content } from '@voxgig/sdkgen'
+
+
+// Emits test/TReadmeExamples.hs — a STRUCTURAL gate over every fenced
+// Haskell code block in the three docs that ship Haskell examples:
+//   - the root README.md (top-level, multi-language quick start)
+//   - the per-language haskell/README.md
+//   - the per-language haskell/REFERENCE.md
+//
+// DESIGN NOTE vs the Python gate (ReadmeExamplesTest_py.ts): the Python
+// version parses AND executes every block in a seeded test-mode subprocess.
+// A faithful Haskell port would compile every snippet against the generated
+// SDK — a throwaway module per block plus a GHC invocation — a large,
+// environment-sensitive harness that cannot be authored safely without a build
+// to validate it. This gate instead validates that every documented Haskell
+// block is PRESENT, non-empty, and STRUCTURALLY well-formed (balanced
+// delimiters). Missing docs are tolerated (a run may generate a subset of
+// phases), and no blocks found records no failures — so this never breaks the
+// shared runner. Upgrading it to a true compile gate is left as a follow-up.
+//
+// The emitted module exposes `tests :: Counters -> IO ()`; the generated
+// SdkGenTests calls it, so it runs inside the standard Runner. The triple
+// backtick fence marker is built from its char code (toEnum 96) so this
+// component's Haskell source needs no backtick/backslash gymnastics.
+const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const Name = model.const.Name
+
+  File({ name: 'TReadmeExamples.' + target.ext }, () => {
+    Content(`-- ${Name} SDK — documentation Haskell-examples structural gate.
+--
+-- Validates that every fenced Haskell code block in the SDK docs (the root
+-- README.md, the per-language README.md, and REFERENCE.md) is present,
+-- non-empty, and has balanced delimiters. Missing docs are tolerated (a run
+-- may generate a subset of phases), so this gate never breaks the shared
+-- runner. See ReadmeExamplesTest_haskell for why this is a structural gate
+-- rather than a full compile harness. Generated by @voxgig/sdkgen.
+
+{-# LANGUAGE ScopedTypeVariables #-}
+
+module TReadmeExamples (tests) where
+
+import Control.Exception (SomeException, evaluate, try)
+import Control.Monad (forM_)
+
+import Testutil (Counters, runTest)
+
+
+-- True for the whitespace characters we trim: space, tab, carriage return.
+isWs :: Char -> Bool
+isWs ch = let n = fromEnum ch in n == 32 || n == 9 || n == 13
+
+
+-- Trim leading/trailing whitespace from a line.
+trimWs :: String -> String
+trimWs = f . f
+  where f = reverse . dropWhile isWs
+
+
+-- Read a doc file, tolerating absence (returns "" when missing/unreadable).
+readDoc :: FilePath -> IO String
+readDoc path = do
+  r <- try (do s <- readFile path; _ <- evaluate (length s); pure s)
+         :: IO (Either SomeException String)
+  pure (either (const "") id r)
+
+
+-- Extract the body of every fenced Haskell block from markdown. The fence
+-- marker (three backticks) is built from its char code so this source stays
+-- backtick-free.
+haskellBlocks :: String -> [String]
+haskellBlocks src = go (lines src)
+  where
+    fence3 = replicate 3 (toEnum 96 :: Char)
+    fenceHs = fence3 ++ "haskell"
+    go [] = []
+    go (l : ls)
+      | trimWs l == fenceHs =
+          let (blk, rest) = break (\\x -> trimWs x == fence3) ls
+          in unlines blk : go (drop 1 rest)
+      | otherwise = go ls
+
+
+-- Balanced (), [], {} ignoring the contents of double-quoted string literals.
+-- The generated snippets never embed an escaped quote inside a string.
+balanced :: String -> Bool
+balanced = go False (0 :: Int)
+  where
+    go inStr d [] = not inStr && d == 0
+    go inStr d (c : cs)
+      | c == '"'                          = go (not inStr) d cs
+      | inStr                             = go inStr d cs
+      | c == '(' || c == '[' || c == '{'  = go inStr (d + 1) cs
+      | c == ')' || c == ']' || c == '}'  =
+          if d <= 0 then False else go inStr (d - 1) cs
+      | otherwise                         = go inStr d cs
+
+
+-- The three documents held to the gate, tagged by human label.
+docs :: [(String, FilePath)]
+docs =
+  [ ("root README", "../README.md")
+  , ("${target.name} README", "README.md")
+  , ("${target.name} REFERENCE", "REFERENCE.md")
+  ]
+
+
+tests :: Counters -> IO ()
+tests c =
+  forM_ docs (\\(label, path) -> do
+    src <- readDoc path
+    let blocks = haskellBlocks src
+    forM_ (zip [1 :: Int ..] blocks) (\\(i, blk) ->
+      runTest c (label ++ " haskell block " ++ show i ++ " well-formed")
+        (pure (not (null (trimWs blk)) && balanced blk))))
+`)
+  })
+})
+
+
+export {
+  ReadmeExamplesTest
+}

package/project/.sdk/src/cmp/haskell/ReadmeExplanation_haskell.ts

@@ -0,0 +1,48 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
+  const { target, ctx$: { model } } = props
+
+  Content(`### Data as struct Values
+
+The Haskell SDK models every API record as the dynamic \`Value\` type (from
+the vendored \`VoxgigStruct\` module) rather than bespoke Haskell records.
+This mirrors the dynamic nature of the API and keeps the SDK flexible — no
+new datatypes or code generation are needed when the API schema changes.
+
+Build request maps with \`jo [(key, value)]\` and read fields back with
+\`getp value "field"\`; scalars are the \`VStr\` / \`VNum\` / \`VBool\`
+constructors, and \`VNoval\` stands for an absent property.
+
+### Module structure
+
+\`\`\`
+${target.name}/
+├── src/
+│   ├── VoxgigStruct.hs   -- vendored dependency-free struct library (Value)
+│   ├── Vregex.hs         -- vendored regex support
+│   ├── SdkTypes.hs       -- core types (Client, Entity, Feature)
+│   ├── SdkHelpers.hs     -- helper functions (jo, getp, ...)
+│   ├── SdkRuntime.hs     -- the generic operation pipeline
+│   ├── SdkFeatures.hs    -- built-in features + makeEntity
+│   ├── SdkConfig.hs      -- generated API configuration + feature factory
+│   └── SdkClient.hs      -- generated public client (newSdk, entity accessors)
+├── test/                 -- test suites
+├── Makefile              -- stock-GHC build/test (no third-party deps)
+└── ${model.const.Name.toLowerCase()}-sdk.cabal      -- package manifest (for Hackage)
+\`\`\`
+
+The public module (\`SdkClient\`) exports the SDK constructors (\`newSdk\`,
+\`testSdk\`) and one accessor per entity. Import \`VoxgigStruct\` for the
+\`Value\` constructors and \`SdkHelpers\` for \`jo\` / \`getp\`.
+
+`)
+
+})
+
+
+export {
+  ReadmeExplanation
+}