@voxgig/sdkgen 1.2.1 → 1.3.2

package/src/helpers/packageMeta.ts

@@ -0,0 +1,236 @@
+// Single source of truth for a generated SDK's PUBLISHED identity and its
+// descriptive metadata, shared by the per-language Package_<lang>.ts manifest
+// generators AND the README install/heading components — so the install
+// command a README prints can never drift from the real published package name
+// (the #1 defect the publishing recommendations call out).
+//
+// The recommendations require, for every package:
+//   - install commands that match the real package name EXACTLY;
+//   - description "Unofficial generated <Lang> SDK for the <API> public API.";
+//   - a generic non-affiliation statement (upstream owner names are unreliable);
+//   - homepage / repository / issues under github.com/<origin>/<slug>-sdk;
+//   - the fixed keyword set [voxgig sdk generated-sdk openapi api-client <slug>].
+//
+// Every value here is derived from the resolved model (model.name, model.origin,
+// main.kit.info.title) — no new inputs required.
+
+import { KIT, nom } from '@voxgig/apidef'
+
+const PUBLISHER = 'Voxgig'
+const PUBLISHER_URL = 'https://voxgig.com'
+const SECURITY_EMAIL = 'security@voxgig.com'
+const GENERATOR_URL = 'https://github.com/voxgig/sdkgen'
+
+const LANG_LABEL: Record<string, string> = {
+  ts: 'TypeScript',
+  js: 'JavaScript',
+  py: 'Python',
+  php: 'PHP',
+  rb: 'Ruby',
+  lua: 'Lua',
+  go: 'Go',
+  'go-cli': 'Go CLI',
+  'go-mcp': 'Go MCP server',
+}
+
+function langLabel(target: string): string {
+  return LANG_LABEL[target] || target
+}
+
+// GitHub org (publisher slug), repo name, and the canonical repo URLs.
+function repoInfo(model: any) {
+  const slug = model.name
+  const origin = model.origin || 'voxgig-sdk'
+  const repo = `${slug}-sdk`
+  const repoUrl = `https://github.com/${origin}/${repo}`
+  return {
+    slug,
+    origin,
+    repo,
+    repoUrl,
+    issuesUrl: `${repoUrl}/issues`,
+    changelogUrl: `${repoUrl}/blob/main/CHANGELOG.md`,
+    // Version-agnostic releases page: where the `<target>/vX.Y.Z` git tags
+    // that a pending (not-yet-on-registry) package is installed from live.
+    releasesUrl: `${repoUrl}/releases`,
+  }
+}
+
+
+// Publication state of a target's package registry, tri-state + tag-only:
+//   'tag'      — no registry (the go family); resolved from the git tag.
+//   'pending'  — registry declared but the package is not uploaded yet
+//                (the fleet default): install from the git tag.
+//   'active'   — package is live on the registry: show the real install cmd.
+//   'inactive' — registry deliberately disabled (tag-only, like pending).
+// Reads main.kit.target.<t>.publish.registry.state (default 'pending').
+// The legacy boolean `registry.active: true` is honoured as a back-compat
+// alias for state === 'active'.
+function registryState(model: any, target: string): 'tag' | 'pending' | 'active' | 'inactive' {
+  if ('go' === target || 'go-cli' === target || 'go-mcp' === target) return 'tag'
+  const reg = model?.main?.[KIT]?.target?.[target]?.publish?.registry
+  if (null == reg || '' === (reg.name || '')) return 'tag'
+  if (true === reg.active) return 'active' // legacy alias
+  const s = reg.state
+  if ('active' === s || 'inactive' === s || 'pending' === s) return s
+  return 'pending'
+}
+
+// True only when the package is actually live on its registry (so a README
+// may print the real `npm install`/`pip install`/... command). Everything
+// else — pending, inactive, tag-only — installs from the git tag instead.
+function isPublished(model: any, target: string): boolean {
+  return 'active' === registryState(model, target)
+}
+
+// The registry a target uploads to (npm | pypi | packagist | ...), or ''
+// for tag-only ports. Used in the "not yet on <registry>" pending message.
+function registryName(model: any, target: string): string {
+  const reg = model?.main?.[KIT]?.target?.[target]?.publish?.registry
+  return (reg && reg.name) ? String(reg.name) : ''
+}
+
+// The vendor / git-tag install pointer for a NOT-yet-published target. For
+// the go family this is the canonical install (`go get <module>@latest`,
+// which the Go proxy resolves from the `<subdir>/vX.Y.Z` tag). For registry
+// ports it is a short "not yet on <registry> — install from the git tag"
+// pointer carrying the releases URL.
+function vendorCommand(model: any, target: string): string {
+  const { releasesUrl } = repoInfo(model)
+  switch (target) {
+    case 'go':
+      return `go get ${packageName(model, 'go')}@latest`
+    case 'go-mcp':
+      return `go get ${packageName(model, 'go-mcp')}@latest`
+    case 'go-cli':
+      return `go install ${packageName(model, 'go-cli')}/cmd/${model.name}@latest`
+    default: {
+      const reg = registryName(model, target)
+      return `not yet on ${reg || 'the registry'} — install from the git tag: ${releasesUrl}`
+    }
+  }
+}
+
+// API display name for descriptions, e.g. "Aare.guru". Uses the OpenAPI
+// info.title (present for ~98% of the fleet), stripping a trailing " API" so
+// we don't render "... Aare.guru API public API". Falls back to the normalised
+// SDK Name, then the slug.
+function apiName(model: any): string {
+  const info = (model.main && model.main[KIT] && model.main[KIT].info) || {}
+  const raw = (null != info.title ? String(info.title) : '').trim()
+  const stripped = raw.replace(/\s*API\s*$/i, '').trim()
+  return stripped || nom(model, 'Name') || model.name
+}
+
+// The REAL published package name per ecosystem — mirrors the exact formula in
+// each Package_<lang>.ts. This is the one canonical implementation.
+function packageName(model: any, eco: string): string {
+  const slug = model.name
+  const origin = model.origin || 'voxgig-sdk'
+  const base = origin.endsWith('-sdk') ? slug : `${slug}-sdk`
+  const npmScoped = `@${origin}/${slug}${origin.endsWith('-sdk') ? '' : '-sdk'}`
+  switch (eco) {
+    case 'npm':
+    case 'ts':
+      return npmScoped
+    case 'js':
+      return `${npmScoped}-js`
+    case 'pypi':
+    case 'py':
+    case 'gem':
+    case 'rb':
+    case 'luarocks':
+    case 'lua':
+      return `${origin}-${base}`
+    case 'composer':
+    case 'php':
+      return `${origin}/${base}`
+    case 'go':
+      return `github.com/${origin}/${slug}-sdk/go`
+    case 'go-cli':
+      return `github.com/${origin}/${slug}-sdk/go-cli`
+    case 'go-mcp':
+      return `github.com/${origin}/${slug}-sdk/go-mcp`
+    default:
+      return `${origin}-${base}`
+  }
+}
+
+// Copy-paste install command for a target, using the REAL package name.
+// Only a package that is actually live on its registry (isPublished) gets a
+// registry install command; everything else (pending / inactive / tag-only,
+// including the whole go family) returns the git-tag vendor command instead,
+// so a README never prints a `npm install ...` that 404s.
+function installCommand(model: any, target: string): string {
+  if (!isPublished(model, target)) {
+    return vendorCommand(model, target)
+  }
+  switch (target) {
+    case 'ts':
+      return `npm install ${packageName(model, 'npm')}`
+    case 'js':
+      return `npm install ${packageName(model, 'js')}`
+    case 'py':
+      return `pip install ${packageName(model, 'pypi')}`
+    case 'php':
+      return `composer require ${packageName(model, 'composer')}`
+    case 'rb':
+      return `gem install ${packageName(model, 'gem')}`
+    case 'lua':
+      return `luarocks install ${packageName(model, 'luarocks')}`
+    case 'go':
+      return `go get ${packageName(model, 'go')}`
+    case 'go-cli':
+      return `go install ${packageName(model, 'go-cli')}/cmd/${model.name}@latest`
+    default:
+      return ''
+  }
+}
+
+// The standard one-line package description (with the generic non-affiliation
+// statement inline) used in every manifest.
+function pkgDescription(model: any, target: string): string {
+  return `Unofficial generated ${langLabel(target)} SDK for the ${apiName(model)} public API.` +
+    ` Not affiliated with or endorsed by the upstream API provider.`
+}
+
+// Longer non-affiliation / generated-code disclosure for READMEs, LICENSE and
+// SECURITY.md. Generic on the upstream owner (owner names are only ~45%
+// reliably known across the fleet).
+function nonAffiliation(model: any): string {
+  return `This is an unofficial SDK for the ${apiName(model)} public API, generated by ` +
+    `${PUBLISHER} with [\`@voxgig/sdkgen\`](${GENERATOR_URL}). ` +
+    `It is not affiliated with, endorsed by, or sponsored by the upstream API provider.`
+}
+
+function keywords(model: any): string[] {
+  return ['voxgig', 'sdk', 'generated-sdk', 'openapi', 'api-client', model.name]
+}
+
+// A VALID uppercase env-var base derived from the slug: 'unsolicited-advice' ->
+// 'UNSOLICITED_ADVICE'. Use for <NAME>_APIKEY / <NAME>_TEST_LIVE so examples are
+// valid identifiers (model.NAME left a hyphen in, breaking process.env.X).
+function envName(model: any): string {
+  return String(model.name || '').toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '')
+}
+
+export {
+  PUBLISHER,
+  PUBLISHER_URL,
+  SECURITY_EMAIL,
+  GENERATOR_URL,
+  LANG_LABEL,
+  langLabel,
+  repoInfo,
+  apiName,
+  packageName,
+  installCommand,
+  registryState,
+  isPublished,
+  registryName,
+  vendorCommand,
+  pkgDescription,
+  nonAffiliation,
+  keywords,
+  envName,
+}

package/src/sdkgen.ts

@@ -19,16 +19,21 @@ import type {
   ActionResult,
 } from './types'
 
-import { SdkGenError, requirePath, isAuthActive } from './utility'
+import { SdkGenError, requirePath, isAuthActive, resolveAuthPrefix } from './utility'
 
 import { Main } from './cmp/Main'
+import { Deploy } from './cmp/Deploy'
 import { Entity } from './cmp/Entity'
 import { Feature } from './cmp/Feature'
 import { Readme } from './cmp/Readme'
 import { ReadmeTop } from './cmp/ReadmeTop'
+import { License } from './cmp/License'
+import { Security } from './cmp/Security'
+import { Changelog } from './cmp/Changelog'
 import { Test } from './cmp/Test'
 import { ReadmeInstall } from './cmp/ReadmeInstall'
 import { ReadmeQuick } from './cmp/ReadmeQuick'
+import { ReadmeErrors } from './cmp/ReadmeErrors'
 import { ReadmeIntro } from './cmp/ReadmeIntro'
 import { ReadmeModel } from './cmp/ReadmeModel'
 import { ReadmeOptions } from './cmp/ReadmeOptions'
@@ -42,6 +47,28 @@ import { buildIdNames } from './helpers/buildIdNames'
 import { getMatchEntries } from './helpers/getMatchEntries'
 import { collectDeps } from './helpers/collectDeps'
 import type { DepEntry } from './helpers/collectDeps'
+import { canonToType, canonKey } from './helpers/canonType'
+import { OP_SUFFIX, opTypeName, opParams, opRequestShape, entityIdField, entityDataIdField, entityOps, entityPrimaryOp } from './helpers/opShape'
+import { isReservedName, safeVarName } from './helpers/naming'
+import {
+  packageName,
+  installCommand,
+  registryState,
+  isPublished,
+  registryName,
+  vendorCommand,
+  pkgDescription,
+  nonAffiliation,
+  keywords,
+  envName,
+  repoInfo,
+  apiName,
+  langLabel,
+  PUBLISHER,
+  PUBLISHER_URL,
+  SECURITY_EMAIL,
+  GENERATOR_URL,
+} from './helpers/packageMeta'
 
 
 import {
@@ -95,14 +122,15 @@ const ACTION_MAP: any = {
 const dlog = getdlog('sdkgen', __filename)
 
 
-let aontu: any = null
-
-
 function SdkGen(opts: SdkGenOptions) {
   const fs = opts.fs || Fs
   const folder = opts.folder || '../'
   const now = opts.now || (() => Date.now())
 
+  // Per-instance cache of the Aontu model loader. Previously a module-level
+  // global, which leaked the (relative) preload across SdkGen instances.
+  let aontu: any = null
+
   const jopts = {
     now,
     control: {
@@ -130,7 +158,7 @@ function SdkGen(opts: SdkGenOptions) {
 
     let Root = spec.root
 
-    if (null == Root && null != config.root) {
+    if (null == Root && null != config?.root) {
       clear(config.root)
       const rootModule: any = require(config.root)
       Root = rootModule.Root
@@ -198,17 +226,11 @@ function SdkGen(opts: SdkGenOptions) {
 
 
   function resolveModel() {
-    const path = './model/sdk.jsonic'
+    const path = './model/sdk.aontu'
     const errs: any[] = []
 
     if (null == aontu) {
-      aontu = new Aontu({
-        preload: {
-          folders: ['./model'],
-          ext: ['.jsonic', '.json'],
-          recursive: true,
-        }
-      })
+      aontu = new Aontu()
     }
 
     const aopts = { path, errs }
@@ -217,17 +239,16 @@ function SdkGen(opts: SdkGenOptions) {
     const model = aontu.generate(src, aopts)
 
     if (0 < errs.length) {
-      for (let serr of errs) {
-        let err: any = new SdkGenError('Model Error: ' + serr.msg)
-        err.cause$ = [serr]
+      const serr = errs[0]
+      const err: any = new SdkGenError('Model Error: ' + serr.msg)
+      err.cause$ = [serr]
 
-        if ('syntax' === serr.why) {
-          err.uxmsg$ = true
-        }
-
-        err.rooterrs$ = errs
-        throw err
+      if ('syntax' === serr.why) {
+        err.uxmsg$ = true
       }
+
+      err.rooterrs$ = errs
+      throw err
     }
 
     model.const = { name: model.name }
@@ -278,7 +299,7 @@ SdkGen.makeBuild = async function(opts: SdkGenOptions) {
     root: opts.root,
     def: opts.def || 'no-def',
     kind: 'openapi-3',
-    model: opts.model ? (opts.model.folder + '/api.jsonic') : 'no-model',
+    model: opts.model ? (opts.model.folder + '/api.aontu') : 'no-model',
     meta: opts.meta || {},
   }
 
@@ -338,6 +359,16 @@ export type {
   DepEntry,
 }
 
+export type {
+  SdkModel,
+  ModelKit,
+  ModelTarget,
+  ModelFeature,
+  ModelEntity,
+  ModelDep,
+  ModelHook,
+} from './types'
+
 
 
 type Component = (props: any, children?: any) => void
@@ -375,6 +406,10 @@ export const List: Component = JostracaModule.List
 
 export {
   Main,
+  Deploy,
+  License,
+  Security,
+  Changelog,
   Entity,
   Feature,
   Test,
@@ -382,6 +417,7 @@ export {
   ReadmeTop,
   ReadmeInstall,
   ReadmeQuick,
+  ReadmeErrors,
   ReadmeIntro,
   ReadmeModel,
   ReadmeOptions,
@@ -396,8 +432,40 @@ export {
 
   requirePath,
   isAuthActive,
+  resolveAuthPrefix,
 
   buildIdNames,
   getMatchEntries,
   collectDeps,
+  canonToType,
+  canonKey,
+
+  OP_SUFFIX,
+  opTypeName,
+  opParams,
+  opRequestShape,
+  entityIdField,
+  entityDataIdField,
+  entityOps,
+  entityPrimaryOp,
+  isReservedName,
+  safeVarName,
+
+  packageName,
+  installCommand,
+  registryState,
+  isPublished,
+  registryName,
+  vendorCommand,
+  pkgDescription,
+  nonAffiliation,
+  keywords,
+  envName,
+  repoInfo,
+  apiName,
+  langLabel,
+  PUBLISHER,
+  PUBLISHER_URL,
+  SECURITY_EMAIL,
+  GENERATOR_URL,
 }

package/src/tsconfig.json

@@ -3,6 +3,7 @@
     "esModuleInterop": true,
     "module": "nodenext",
     "noEmitOnError": true,
+    "skipLibCheck": true,
     "outDir":"../dist",
     "rootDir":".",
     "resolveJsonModule": true,

package/src/types.ts

@@ -14,11 +14,88 @@ import {
 type FsUtil = typeof Fs
 
 
+// The model is produced by aontu/apidef and carries dynamic metadata
+// (key$, val$, index$, and the Name/NAME case variants injected by
+// jostraca's names()). These interfaces document the fields sdkgen relies
+// on while the index signatures keep the genuinely-dynamic remainder
+// accessible — a pragmatic middle ground until the model is shaped with
+// `shape`.
+
+// Case variants injected by jostraca's names() helper.
+type NameCases = {
+  name?: string
+  Name?: string
+  NAME?: string
+}
+
+// A dependency entry inside a target or feature `deps` block.
+type ModelDep = {
+  key$?: string
+  version?: string
+  active?: boolean
+  kind?: string
+  replace?: string
+  [extra: string]: any
+}
+
+type ModelHook = {
+  active?: boolean
+  [extra: string]: any
+}
+
+type ModelFeature = NameCases & {
+  active?: boolean
+  title?: string
+  version?: string
+  hook?: Record<string, ModelHook>
+  deps?: Record<string, Record<string, ModelDep>>
+  [extra: string]: any
+}
+
+type ModelTarget = NameCases & {
+  active?: boolean
+  title?: string
+  base?: string
+  module?: { name?: string }
+  srcfeature?: boolean
+  [extra: string]: any
+}
+
+type ModelEntity = NameCases & {
+  active?: boolean
+  short?: string
+  desc?: string
+  op?: Record<string, any>
+  relations?: { ancestors?: any }
+  [extra: string]: any
+}
+
+type ModelKit = {
+  info?: Record<string, any>
+  config?: Record<string, any>
+  target?: Record<string, ModelTarget>
+  feature?: Record<string, ModelFeature>
+  entity?: Record<string, ModelEntity>
+  [extra: string]: any
+}
+
+type SdkModel = NameCases & {
+  origin?: string
+  const?: Record<string, any>
+  main: {
+    kit?: ModelKit
+    def?: Record<string, any>
+    [extra: string]: any
+  }
+  [extra: string]: any
+}
+
+
 type ActionContext = {
   fs: () => FsUtil,
   log: any,
   folder: string,
-  model: any,
+  model: SdkModel,
   url: string,
   opts: any,
   jostraca: any
@@ -38,5 +115,11 @@ export {
 export type {
   ActionContext,
   ActionResult,
+  SdkModel,
+  ModelKit,
+  ModelTarget,
+  ModelFeature,
+  ModelEntity,
+  ModelDep,
+  ModelHook,
 }
-

package/src/utility.ts

@@ -12,31 +12,64 @@ function resolvePath(ctx$: any, path: string): any {
 }
 
 
-// True unless the model explicitly declares main.kit.config.auth.active: false.
-// Used by templates to gate apikey-related code, docs, and examples for
-// public APIs that need no authentication.
+// True unless the model declares auth off. Templates use this to gate
+// apikey-related code, docs, and examples for public APIs that need no
+// authentication. Two opt-outs, in priority order:
+//   1. main.kit.info.auth: false        (user-facing, set in api-info.aontu)
+//   2. main.kit.config.auth.active: false
 function isAuthActive(model: any): boolean {
+  const info = getModelPath(model, `main.${KIT}.info`,
+    { only_active: false, required: false })
+  if (info && false === info.auth) return false
+
   const auth = getModelPath(model, `main.${KIT}.config.auth`,
     { only_active: false, required: false })
   return null == auth || false !== auth.active
 }
 
 
+// The credential prefix for the Authorization header value, resolved in
+// priority order:
+//   1. main.kit.config.auth.prefix   (per-SDK user override)
+//   2. main.kit.info.security.prefix (spec-derived, set by apidef from the
+//      API's securityScheme — e.g. 'OAuth' for Statuspage)
+//   3. 'Bearer'                      (conventional fallback)
+// '' is a valid resolved value: it means a raw credential with no prefix
+// (e.g. an apiKey scheme in a custom header). Config generators for every
+// language target must use this instead of hardcoding 'Bearer'.
+function resolveAuthPrefix(model: any): string {
+  const auth = getModelPath(model, `main.${KIT}.config.auth`,
+    { only_active: false, required: false })
+  if (null != auth && null != auth.prefix) return String(auth.prefix)
+
+  const security = getModelPath(model, `main.${KIT}.info.security`,
+    { only_active: false, required: false })
+  if (null != security && null != security.prefix) return String(security.prefix)
+
+  return 'Bearer'
+}
+
+
 function requirePath(ctx$: any, path: string, flags?: { ignore?: boolean }): any {
   const fullpath = resolvePath(ctx$, path)
   const ignore = null == flags?.ignore ? false : flags.ignore
 
-  try {
-    return require(fullpath)
-  }
-  catch (err: any) {
-    if (ignore) {
-      ctx$.log.warn({ point: 'require-missing', path, note: path })
+  // When `ignore` is set, only swallow a genuine "module not found"
+  // resolution failure. A module that resolves but throws while loading
+  // (syntax error, runtime bug, or a missing *nested* dependency) must
+  // propagate — otherwise the optional component silently renders nothing
+  // and the real failure is invisible.
+  if (ignore) {
+    try {
+      require.resolve(fullpath)
     }
-    else {
-      throw err
+    catch (err: any) {
+      ctx$.log.warn({ point: 'require-missing', path, note: path })
+      return undefined
     }
   }
+
+  return require(fullpath)
 }
 
 
@@ -52,5 +85,6 @@ export {
   resolvePath,
   requirePath,
   isAuthActive,
+  resolveAuthPrefix,
   SdkGenError,
 }

package/README.md

@@ -1,2 +0,0 @@
-# sdkgen
-Voxgig SDK Generator

package/dist/action/lang.d.ts

@@ -1,2 +0,0 @@
-declare function action_lang(args: any[], ctx: any): Promise<void>;
-export { action_lang };