@voxgig/sdkgen 1.2.1 → 1.3.1

package/src/cmp/ReadmeTop.ts

@@ -8,47 +8,322 @@ import {
 
 import { requirePath } from '../utility'
 
+import { entityPrimaryOp, entityIdField, opRequestShape } from '../helpers/opShape'
+import { canonKey } from '../helpers/canonType'
+import { safeVarName } from '../helpers/naming'
+
+import {
+  installCommand as pkgInstall,
+  packageName,
+  registryState,
+  vendorCommand,
+  apiName,
+  nonAffiliation,
+  repoInfo,
+  SECURITY_EMAIL,
+} from '../helpers/packageMeta'
+
+
+const SDKGEN_REPO = 'https://github.com/voxgig/sdkgen'
+
+
+// A type-correct TS example literal for a model field, keyed off its canonical
+// type sentinel — mirrors the per-language `exampleValue`, but inline because
+// this neutral component renders the intro `ts` block directly.
+function tsExampleLiteral(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return '[]'
+  if ('OBJECT' === k) return '{}'
+  return `'example'`
+}
+
+
+// Per-language install commands rendered in the top-level "Try it"
+// section. The per-language `ReadmeInstall_<lang>.ts` templates exist
+// but emit extra prose ("Or install from source: ..."); for the
+// landing-page README we want a single copy-paste line per language.
+function installCommand(target: any, model: any): string {
+  // Delegate to the single source of truth so the README install command can
+  // never drift from the real published package name (see helpers/packageMeta).
+  return pkgInstall(model, target.name)
+}
+
+
+// Pick the language we lead the README with — first entry from the
+// docs-ordered SDK targets. Returns undefined if there are no targets.
+function pickLeadTarget(sdkTargets: any[]): any | undefined {
+  return sdkTargets[0]
+}
+
 
 const ReadmeTop = cmp(function ReadmeTop(props: any) {
   const { ctx$ } = props
   const { model } = ctx$
 
-  const desc = model.main.def.desc || ''
+  // Ensure the Name/NAME case variants exist (apidef usually sets these,
+  // but guard so the header never renders "undefined SDK"). Entity/feature
+  // names are guarded the same way below.
+  if (model.name && !model.Name) names(model, model.name)
+
+  const info = (model.main && model.main[KIT] && model.main[KIT].info) || {}
+  const def = (model.main && model.main.def) || {}
+
+  // Plain-text title — prefer the OpenAPI `info.title` when it's
+  // recognisably the product name (e.g. "Aare.guru API"), fall back
+  // to the normalised SDK Name.
+  const productName = info.title || `${model.Name} API`
+
+  const tagline = info.tagline
+    || def.tagline
+    || `${productName} client, generated from the OpenAPI spec.`
+
+  const aboutMd = info.about_md || ''
+  const licenseMd = info.license_md || ''
+  const licenseShort = info.license_short || ''
+  const homepage = info.homepage || ''
+  const docsUrl = info.docs_url || ''
+  const entityDesc = info.entity_desc || {}
+
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const target = getModelPath(model, `main.${KIT}.target`)
   const feature = getModelPath(model, `main.${KIT}.feature`)
 
-  // Ensure names are computed on entities and features
   each(entity, (ent: any) => { if (!ent.Name) names(ent, ent.name) })
   each(feature, (feat: any) => { if (!feat.Name) names(feat, feat.name) })
 
   const activeEntities = each(entity).filter((e: any) => e.active !== false)
-  const activeTargets = each(target)
+  const activeTargets = each(target).filter((t: any) => t.active !== false)
+
+  const hasCli = activeTargets.some((t: any) => t.name === 'go-cli')
+  const hasMcp = activeTargets.some((t: any) => t.name === 'go-mcp')
+  const hasJsLike = activeTargets.some((t: any) => t.name === 'ts' || t.name === 'js')
+
+  // Canonical docs order from main.kit.config.docs_order (with a
+  // schema-supplied default of ['ts','py','php','go','rb','lua']).
+  // Targets present but not listed get appended in spec-defined order,
+  // so adding a new target never silently disappears from the docs.
+  const docsOrder: string[] = (getModelPath(model, `main.${KIT}.config.docs_order`,
+    { only_active: false, required: false }) as any) || []
+
+  const sdkTargets = activeTargets
+    .filter((t: any) => t.name !== 'go-cli' && t.name !== 'go-mcp')
+    .slice()
+    .sort((a: any, b: any) => {
+      const ai = docsOrder.indexOf(a.name)
+      const bi = docsOrder.indexOf(b.name)
+      const av = ai === -1 ? docsOrder.length : ai
+      const bv = bi === -1 ? docsOrder.length : bi
+      return av - bv
+    })
+
+  const langList = sdkTargets.map((t: any) => t.title).join(', ')
+  const leadTarget = pickLeadTarget(sdkTargets)
 
   File({ name: 'README.md' }, () => {
 
+    // 1. H1 + one-line value prop + unofficial / non-affiliation disclosure
     Content(`# ${model.Name} SDK
 
-${desc}
+${tagline}
+
+${nonAffiliation(model)}
 
 `)
 
-    // Target links
-    if (activeTargets.length > 0) {
-      Content(`Available for `)
-      const links = activeTargets.map((t: any) =>
-        `[${t.title}](${t.name}/)`
-      )
-      Content(`${links.join(' and ')}.
+    // Positioning line, only when we actually have multiple SDK targets.
+    if (sdkTargets.length > 1) {
+      const surfaces = []
+      surfaces.push(`${langList} SDKs`)
+      if (hasCli) surfaces.push('a CLI')
+      if (hasJsLike) surfaces.push('an interactive REPL')
+      if (hasMcp) surfaces.push('an MCP server for AI agents')
+      const surfaceList = surfaces.length > 1
+        ? surfaces.slice(0, -1).join(', ') + ', and ' + surfaces[surfaces.length - 1]
+        : surfaces[0]
+      Content(`> ${surfaceList} — all generated from one OpenAPI spec by [@voxgig/sdkgen](${SDKGEN_REPO}).
 
 `)
     }
 
+    // 2. About / what the API is
+    if (aboutMd) {
+      Content(`## About ${productName}
 
-    // Entities section
+${aboutMd.trim()}
+
+`)
+    } else if (def.desc) {
+      Content(`${def.desc}
+
+`)
+    }
+
+    // 2b. Entities-first framing: the API surface is a small set of semantic,
+    // Capitalised entities — NOT raw URL paths/queries — which is the core
+    // mental model the SDK is built around (model-driven; lists real entities).
     if (activeEntities.length > 0) {
+      const entNames = activeEntities.map((e: any) => e.Name)
+      const entList = entNames.length > 1
+        ? entNames.slice(0, -1).join(', ') + ' and ' + entNames[entNames.length - 1]
+        : entNames[0]
+      const exEnt = activeEntities[0]
+      const ex = exEnt.Name
+      const exLower = safeVarName(ex.toLowerCase(), 'ts')
+      // The example call uses the entity's PRIMARY op — an op it actually
+      // exposes (prefer list -> the array, then load -> the record, else a
+      // create with its required fields). A create-only entity therefore never
+      // shows a phantom .list()/.load() that would not compile. If it exposes
+      // only remove (or nothing), the op line is omitted entirely.
+      const primaryOp = entityPrimaryOp(exEnt)
+      let exCall = ''
+      if ('list' === primaryOp) {
+        exCall = `const items = await client.${ex}().list()`
+      } else if ('load' === primaryOp) {
+        exCall = `const ${exLower} = await client.${ex}().load()`
+      } else if ('create' === primaryOp || 'update' === primaryOp) {
+        const exIdF = entityIdField(exEnt)
+        const shapeItems = opRequestShape(exEnt, primaryOp).items
+          .filter((it: any) => it.name !== exIdF && it.name !== 'id')
+        const required = shapeItems.filter((it: any) => !it.optional)
+        // ALL required fields must appear or the literal is not assignable to
+        // the typed CreateData/UpdateData; cap only the optional fallback.
+        const chosen = required.length ? required : shapeItems.slice(0, 3)
+        const bodyLines = chosen.map((it: any) => `  ${it.name}: ${tsExampleLiteral(it.type)},`)
+        const body = bodyLines.length ? `\n${bodyLines.join('\n')}\n` : ''
+        exCall = `const ${exLower} = await client.${ex}().${primaryOp}({${body}})`
+      }
+      // Model-driven op list — only the operations the entities actually expose
+      // (advice may be list+load only; never claim create/update/remove exist).
+      const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
+      const opSet = new Set<string>()
+      activeEntities.forEach((e: any) => Object.keys(e.op || {})
+        .forEach((o: string) => { if ((e.op as any)[o] && (e.op as any)[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(`## Entities, not endpoints
+
+This SDK exposes the API as a small set of **semantic entities** — ${entList} — that you
+call directly, instead of assembling URL paths and query strings. Entities are
+**Capitalised** to mark them as the primary surface, each with the operations they
+support (${opList}):
+
+\`\`\`ts
+const client = new ${model.Name}SDK()${exCall ? '\n' + exCall : ''}
+\`\`\`
+
+Thinking in entities keeps the mental model small — for people and AI agents alike —
+rather than reasoning about raw HTTP routes and query parameters.
+
+`)
+    }
+
+    // 3. Packages — real published package name + install command per
+    // ecosystem. A package that is NOT yet live on its registry (the fleet
+    // default: 'pending') must NOT advertise a `npm install ...` that 404s —
+    // its Install cell links to the git-tag releases page instead. The go
+    // family resolves from the tag directly (`go get <mod>@latest`).
+    if (sdkTargets.length > 0) {
+      const { releasesUrl } = repoInfo(model)
+      Content(`## Packages
+
+| Language | Package | Install |
+| --- | --- | --- |
+`)
+      sdkTargets.forEach((tgt: any) => {
+        const state = registryState(model, tgt.name)
+        let cell: string
+        if ('active' === state) {
+          const cmd = installCommand(tgt, model)
+          if (!cmd) return
+          cell = '`' + cmd + '`'
+        } else if ('tag' === state) {
+          // Tag-only port (go): the vendor command IS the real install.
+          cell = '`' + vendorCommand(model, tgt.name) + '`'
+        } else {
+          // pending / inactive: point at the git tag, never a 404 command.
+          cell = `publish pending — [install from git tag](${releasesUrl})`
+        }
+        Content(`| ${tgt.title} | \`${packageName(model, tgt.name)}\` | ${cell} |
+`)
+      })
+      Content(`
+`)
+    }
+
+    // 4. Quickstart in the lead language
+    if (leadTarget) {
+      Content(`## Quickstart
+
+### ${leadTarget.title}
+
+`)
+      const LeadQuick =
+        requirePath(ctx$, `./cmp/${leadTarget.name}/ReadmeTopQuick_${leadTarget.name}`, { ignore: true })
+      if (LeadQuick) {
+        LeadQuick['ReadmeTopQuick']({ target: leadTarget })
+      }
+      Content(`
+See the [${leadTarget.title} README](${leadTarget.name}/README.md) for the full guide.
+
+`)
+    }
+
+    // 5. Surface table
+    if (sdkTargets.length > 0 || hasCli || hasMcp) {
+      Content(`## Surfaces
+
+| Surface | Path |
+| --- | --- |
+`)
+      if (sdkTargets.length > 0) {
+        const paths = sdkTargets.map((t: any) => `\`${t.name}/\``).join(' ')
+        Content(`| **SDK** (${langList}) | ${paths} |
+`)
+      }
+      if (hasCli) {
+        Content(`| **CLI** | \`go-cli/\` |
+`)
+      }
+      if (hasMcp) {
+        Content(`| **MCP server** | \`go-mcp/\` |
+`)
+      }
       Content(`
-## Entities
+`)
+    }
+
+    // 6. MCP / agent usage — only if MCP target is enabled
+    if (hasMcp) {
+      Content(`## Use it from an AI agent (MCP)
+
+The generated MCP server exposes every operation in this SDK as an
+[MCP](https://modelcontextprotocol.io) tool that Claude, Cursor or Cline
+can call directly. Build and register it:
+
+\`\`\`bash
+cd go-mcp && go build -o ${model.name}-mcp .
+\`\`\`
+
+Then add it to your agent's MCP config (Claude Desktop, Cursor, etc.):
+
+\`\`\`json
+{
+  "mcpServers": {
+    "${model.name}": {
+      "command": "/abs/path/to/${model.name}-mcp"
+    }
+  }
+}
+\`\`\`
+
+`)
+    }
+
+    // 7. Entities table
+    if (activeEntities.length > 0) {
+      Content(`## Entities
 
 The API exposes ${activeEntities.length === 1 ? 'one entity' : activeEntities.length + ' entities'}:
 
@@ -57,8 +332,11 @@ The API exposes ${activeEntities.length === 1 ? 'one entity' : activeEntities.le
 `)
 
       activeEntities.map((ent: any) => {
-        const entdesc = ent.short || ''
         const ops = ent.op || {}
+        const opNames = Object.keys(ops).filter((o: string) => (ops as any)[o]?.active !== false)
+        // Never emit a blank description cell: fall back to an ops-derived line.
+        const entdesc = entityDesc[ent.name] || ent.short || ent.desc ||
+          `The ${ent.Name} entity${opNames.length ? ' (' + opNames.join(', ') + ')' : ''}.`
         const points = each(ops).map((op: any) =>
           op.points ? each(op.points) : []
         ).flat()
@@ -69,140 +347,178 @@ The API exposes ${activeEntities.length === 1 ? 'one entity' : activeEntities.le
 `)
       })
 
+      const opUnion = new Set<string>()
+      activeEntities.forEach((e: any) => Object.keys(e.op || {})
+        .forEach((o: string) => { if ((e.op as any)[o]?.active !== false) opUnion.add(o) }))
+      const opAvail = ['load', 'list', 'create', 'update', 'remove'].filter((o) => opUnion.has(o))
+      const opBold = (opAvail.length ? opAvail : ['load', 'list']).map((o) => '**' + o + '**').join(', ')
       Content(`
-Each entity supports the following operations where available: **load**, **list**, **create**,
-**update**, and **remove**.
+The operations available across these entities are ${opBold} — see each entity's
+own list above for exactly which it supports.
 
 `)
     }
 
+    // 8. Quickstart in the other languages (lead is already covered above)
+    const otherTargets = sdkTargets.filter((t: any) => leadTarget && t.name !== leadTarget.name)
+    if (otherTargets.length > 0) {
+      Content(`## Quickstart in other languages
 
-    // Architecture section
-    Content(`
-## Architecture
-
-### Entity-operation model
-
-Every SDK call follows the same pipeline:
-
-1. **Point** — resolve the API endpoint from the operation definition.
-2. **Spec** — build the HTTP specification (URL, method, headers, body).
-3. **Request** — send the HTTP request.
-4. **Response** — receive and parse the response.
-5. **Result** — extract the result data for the caller.
+`)
+      otherTargets.forEach((tgt: any) => {
+        const Quick =
+          requirePath(ctx$, `./cmp/${tgt.name}/ReadmeTopQuick_${tgt.name}`, { ignore: true })
+        if (Quick) {
+          Content(`### ${tgt.title}
 
-At each stage a feature hook fires (e.g. \`PrePoint\`, \`PreSpec\`,
-\`PreRequest\`), allowing features to inspect or modify the pipeline.
+`)
+          Quick['ReadmeTopQuick']({ target: tgt })
+          Content(`
+`)
+        }
+      })
+    }
 
-### Features
+    // 9. Testing — keep, but slim
+    if (sdkTargets.length > 0) {
+      Content(`## Unit testing in offline mode
 
-Features are hook-based middleware that extend SDK behaviour.
+Every SDK ships a test mode that swaps the HTTP transport for an
+in-memory mock, so unit tests run offline.
 
-| Feature | Purpose |
-| --- | --- |
 `)
+      sdkTargets.forEach((tgt: any) => {
+        const Test =
+          requirePath(ctx$, `./cmp/${tgt.name}/ReadmeTopTest_${tgt.name}`, { ignore: true })
+        if (Test) {
+          Content(`### ${tgt.title}
 
-    each(feature, (feat: any) => {
-      if (!feat.active) return
-      const purpose = feat.title || feat.Name || feat.name
-      Content(`| **${feat.Name || feat.name}Feature** | ${purpose} |
 `)
-    })
-
-    Content(`
-You can add custom features by passing them in the \`extend\` option at
-construction time.
+          Test['ReadmeTopTest']({ target: tgt })
+          Content(`
+`)
+        }
+      })
+    }
 
-### Direct and Prepare
+    // 10. Direct and prepare — a common everyday task (the low-level
+    // escape hatch for endpoints the entity model doesn't cover).
+    Content(`## Direct and prepare
 
-For endpoints not covered by the entity model, use the low-level methods:
+For endpoints the entity model doesn't cover, use the low-level methods:
 
 - **\`direct(fetchargs)\`** — build and send an HTTP request in one step.
 - **\`prepare(fetchargs)\`** — build the request without sending it.
 
-Both accept a map with \`path\`, \`method\`, \`params\`, \`query\`, \`headers\`,
-and \`body\`.
+Both accept a map with \`path\`, \`method\`, \`params\`, \`query\`,
+\`headers\`, and \`body\`. See the [How-to guides](#how-to-guides) below.
 
 `)
 
+    // 11. How-to guides — keep, useful for the engineer reader
+    Content(`## How-to guides
 
-    // Quick start section with examples from each target
-    Content(`
-## Quick start
-
-`)
-
-    activeTargets.map((tgt: any) => {
-      const ReadmeTopQuick_sdk =
-        requirePath(ctx$, `./cmp/${tgt.name}/ReadmeTopQuick_${tgt.name}`, { ignore: true })
+### Make a direct API call
 
-      if (ReadmeTopQuick_sdk) {
-        Content(`### ${tgt.title}
+When the entity interface does not cover an endpoint, use \`direct\`:
 
 `)
-        ReadmeTopQuick_sdk['ReadmeTopQuick']({ target: tgt })
-        Content(`
-`)
+
+    sdkTargets.forEach((tgt: any) => {
+      const Howto =
+        requirePath(ctx$, `./cmp/${tgt.name}/ReadmeTopHowto_${tgt.name}`, { ignore: true })
+      if (Howto) {
+        Howto['ReadmeTopHowto']({ target: tgt })
       }
     })
 
+    // 11b. Advanced — the pipeline model and feature hooks are internal
+    // machinery: useful when extending the SDK, but not part of everyday
+    // use, so they live below the task-focused sections above.
+    Content(`## Advanced
 
-    // Testing section
-    Content(`
-## Testing
+> Everyday use only needs the sections above. This explains the internals
+> behind every call — relevant when writing custom features.
 
-Both SDKs provide a test mode that replaces the HTTP transport with an
-in-memory mock, so tests run without a network connection.
+Every SDK call runs the same five-stage pipeline:
 
-`)
+1. **Point** — resolve the API endpoint from the operation definition.
+2. **Spec** — build the HTTP specification (URL, method, headers, body).
+3. **Request** — send the HTTP request.
+4. **Response** — receive and parse the response.
+5. **Result** — extract the result data for the caller.
 
-    activeTargets.map((tgt: any) => {
-      const ReadmeTopTest_sdk =
-        requirePath(ctx$, `./cmp/${tgt.name}/ReadmeTopTest_${tgt.name}`, { ignore: true })
+A feature hook fires at each stage (e.g. \`PrePoint\`, \`PreSpec\`,
+\`PreRequest\`), so features can inspect or modify the pipeline without
+forking the SDK.
 
-      if (ReadmeTopTest_sdk) {
-        Content(`### ${tgt.title}
+### Features
 
 `)
-        ReadmeTopTest_sdk['ReadmeTopTest']({ target: tgt })
-        Content(`
+
+    Content(`| Feature | Purpose |
+| --- | --- |
+`)
+    each(feature, (feat: any) => {
+      if (!feat.active) return
+      const purpose = feat.title || feat.Name || feat.name
+      Content(`| **${feat.Name || feat.name}Feature** | ${purpose} |
 `)
-      }
     })
 
-
-    // How-to guides
     Content(`
-## How-to guides
+Pass custom features via the \`extend\` option at construction time.
 
-### Make a direct API call
+`)
 
-When the entity interface does not cover an endpoint, use \`direct\`:
+    // 12. Per-language docs links
+    if (sdkTargets.length > 0) {
+      Content(`## Per-language documentation
 
 `)
+      sdkTargets.forEach((tgt: any) => {
+        Content(`- [${tgt.title}](${tgt.name}/README.md)
+`)
+      })
+      Content(`
+`)
+    }
 
-    activeTargets.map((tgt: any) => {
-      const ReadmeTopHowto_sdk =
-        requirePath(ctx$, `./cmp/${tgt.name}/ReadmeTopHowto_${tgt.name}`, { ignore: true })
+    // 13. Upstream API — contact/servers from the OpenAPI info block
+    const upstreamUrl = (info.contact && info.contact.url)
+      || (info.servers && info.servers[0] && info.servers[0].url)
+      || homepage
+    if (upstreamUrl || docsUrl) {
+      Content(`## Upstream API
 
-      if (ReadmeTopHowto_sdk) {
-        ReadmeTopHowto_sdk['ReadmeTopHowto']({ target: tgt })
+This SDK is generated from the upstream OpenAPI specification. It is an
+unofficial client and is not affiliated with the API provider.
+
+`)
+      if (upstreamUrl) {
+        Content(`- Upstream API: [${upstreamUrl}](${upstreamUrl})
+`)
       }
-    })
+      if (docsUrl && docsUrl !== upstreamUrl) {
+        Content(`- Documentation: [${docsUrl}](${docsUrl})
+`)
+      }
+      Content(`
+`)
+    }
 
+    // 13b. Security
+    Content(`## Security
 
-    // Language-specific links
-    Content(`
-## Language-specific documentation
+Please report security issues to ${SECURITY_EMAIL}. See [SECURITY.md](SECURITY.md).
+Do not open public issues for suspected vulnerabilities.
 
 `)
 
-    activeTargets.map((tgt: any) => {
-      Content(`- [${tgt.title} SDK](${tgt.name}/README.md)
-`)
-    })
+    // 14. Provenance footer
+    Content(`---
 
-    Content(`
+Generated from the ${productName} OpenAPI spec by [@voxgig/sdkgen](${SDKGEN_REPO}).
 `)
   })
 })

package/src/cmp/Security.ts

@@ -0,0 +1,41 @@
+import { cmp, Content, File } from 'jostraca'
+
+import { SECURITY_EMAIL, apiName, repoInfo } from '../helpers/packageMeta'
+
+
+// Root SECURITY.md: a responsible-disclosure policy pointing at the Voxgig
+// security contact, with the generated / unofficial disclosure inline.
+const Security = cmp(function Security(props: any) {
+  const { ctx$ } = props
+  const { model } = ctx$
+
+  const { issuesUrl } = repoInfo(model)
+
+  File({ name: 'SECURITY.md' }, () => {
+    Content(`# Security Policy
+
+## Reporting a vulnerability
+
+Please report security issues to ${SECURITY_EMAIL}.
+
+Do not open public GitHub issues for suspected vulnerabilities. We aim to
+acknowledge reports within 3 business days.
+
+For non-security bugs, use the issue tracker: ${issuesUrl}
+
+## Scope
+
+This policy applies to the generated Voxgig SDK packages published from this
+repository (npm, PyPI, Packagist, RubyGems, LuaRocks, and the Go module).
+
+This is an unofficial SDK for the ${apiName(model)} public API, generated by
+Voxgig. It is not affiliated with, endorsed by, or sponsored by the upstream
+API provider.
+`)
+  })
+})
+
+
+export {
+  Security
+}