@voxgig/sdkgen 2.0.1 → 3.0.0

package/src/helpers/featureSource.ts

@@ -0,0 +1,208 @@
+// Locate the per-feature source inside a target's template tree.
+//
+// WHY THIS EXISTS
+//
+// `target add` is supposed to copy source for the features the model
+// declares, and nothing else. It used to do that with a single hardcoded
+// path assumption:
+//
+//   Copy({ from: 'tm/<lang>', exclude: [/src\/feature/] })
+//   Folder({ name: 'src/feature' }, () => /* copy each model feature */)
+//
+// That assumption holds for exactly two targets. `ts` and `js` keep feature
+// source at `src/feature/<name>/`; everyone else does something else —
+// `tm/go/feature/retry_feature.go`, `tm/rust/feature/retry.rs`,
+// `tm/py/pkg/feature/retry_feature.py`, `tm/dart/lib/feature/retry/...`,
+// `tm/swift/Sources/ProjectNameSDK/feature/RetryFeature.swift`, and so on.
+// None of those match `src/feature`, so the exclude never saw them and every
+// shipped feature was copied into every project regardless of the model: 272
+// stray source files across 17 targets for a project declaring no features
+// at all. (For those targets `src/feature/<name>/` holds only a `.gitkeep`
+// placeholder — the old gate was gating empty directories.)
+//
+// So instead of encoding one layout, DISCOVER it: walk the template tree,
+// treat any directory named `feature` as a feature container, and map each
+// entry inside it back to a feature name. That covers every layout above,
+// and a target added later gets gated without anyone editing this file.
+//
+// The mapping is deliberately conservative. An entry only counts as feature
+// source when its derived name is one the generator can actually supply
+// (`availableFeatures`, read from `model/feature/*.aontu`). Everything else
+// inside a feature directory — `feature_options.go`, `FeatureOptions.cs`,
+// `mod.rs`, `support.rs`, `options.hpp`, `__init__.py`, `README.md`, and the
+// `harness.ts` under `test/feature/` — derives a name no feature has, so it
+// is left alone.
+
+import Path from 'node:path'
+
+import { KIT, getModelPath } from '@voxgig/apidef'
+
+
+// One feature's source within a target template tree.
+type FeatureSource = {
+  // Feature name, lowercased ('retry').
+  name: string
+
+  // Path relative to the target template root ('feature/retry_feature.go',
+  // 'lib/feature/retry'), always with forward slashes.
+  path: string
+
+  // True when `path` is a directory holding the whole feature.
+  folder: boolean
+}
+
+
+// Directory name that marks a feature container. Kept exact (not a substring
+// match) so `utility/feature_add.go` and `test/feature_test.go` — which are
+// shared machinery, not per-feature source — are never treated as features.
+const FEATURE_DIR = 'feature'
+
+
+// Derive the feature name an entry inside a feature directory belongs to.
+// Returns the lowercased name, which the caller then checks against the
+// available set.
+//
+//   retry_feature.go   -> retry     (go, py, rb, lua, perl)
+//   RetryFeature.cs    -> retry     (csharp, java, kotlin, scala, swift, php)
+//   retry.rs           -> retry     (rust, c, cpp, zig, elixir)
+//   retry/             -> retry     (ts, js, dart)
+//   feature_options.go -> feature_options   (not a feature; `_feature` is a
+//                                            prefix here, not a suffix)
+//   FeatureOptions.cs  -> featureoptions    (ditto)
+function featureOf(entry: string, folder: boolean): string {
+  if (folder) {
+    return entry.toLowerCase()
+  }
+
+  // Only the final extension goes; `feature.test.ts` style names keep the
+  // rest so they cannot collide with a bare feature name.
+  const stem = entry.replace(/\.[^.]+$/, '')
+
+  return stem
+    .replace(/_feature$/i, '')
+    .replace(/Feature$/, '')
+    .toLowerCase()
+}
+
+
+// Feature names this generator can supply, read from the scaffold's
+// `model/feature/*.aontu`. This is the authoritative catalogue: a name not in
+// it is not a feature, so nothing outside it is ever excluded.
+function availableFeatures(fs: any, sdkfolder: string): string[] {
+  const dir = Path.join(sdkfolder, 'model', 'feature')
+
+  if (!fs.existsSync(dir)) {
+    return []
+  }
+
+  return fs.readdirSync(dir)
+    .filter((n: string) => n.endsWith('.aontu') && 'feature-index.aontu' !== n)
+    .map((n: string) => n.replace(/\.aontu$/, '').toLowerCase())
+    .sort()
+}
+
+
+// Walk a target's template tree and return every per-feature source entry.
+// `tmfolder` is the target template root (`<sdk>/tm/<lang>`).
+function findFeatureSources(fs: any, tmfolder: string, available: string[]): FeatureSource[] {
+  const known = new Set(available)
+  const found: FeatureSource[] = []
+
+  if (!fs.existsSync(tmfolder)) {
+    return found
+  }
+
+  // `rel` is relative to tmfolder, '' at the root.
+  const walk = (rel: string) => {
+    const abs = '' === rel ? tmfolder : Path.join(tmfolder, rel)
+    const entries = fs.readdirSync(abs).sort()
+
+    for (const entry of entries) {
+      const entryrel = '' === rel ? entry : rel + '/' + entry
+      const folder = fs.statSync(Path.join(tmfolder, entryrel)).isDirectory()
+
+      // Inside a feature container every entry is a candidate, and a
+      // candidate directory is the whole feature — do not descend into it
+      // looking for more.
+      if (FEATURE_DIR === Path.basename(rel)) {
+        const name = featureOf(entry, folder)
+        if (known.has(name)) {
+          found.push({ name, path: entryrel, folder })
+          continue
+        }
+      }
+
+      if (folder) {
+        walk(entryrel)
+      }
+    }
+  }
+
+  walk('')
+
+  return found
+}
+
+
+// Turn discovered sources into path patterns for a jostraca `Copy` exclude.
+//
+// jostraca tests each candidate against the path built up during its walk,
+// which carries the enclosing node path as a prefix — so anchor on a
+// segment boundary at both ends rather than on the whole string. A folder
+// source matches everything beneath it; a file source matches only itself.
+function featureExcludes(sources: FeatureSource[]): RegExp[] {
+  return sources.map((s) => new RegExp(
+    '(^|/)' + s.path.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + (s.folder ? '/' : '$')
+  ))
+}
+
+
+// Path patterns for templates that only compile with the COMPLETE feature
+// set — see `feature.fullset` in each target's model. These are the
+// cross-feature test suites: one file per target that constructs every
+// shipped feature type by name (`feature.NewRetryFeature`,
+// `RUSTCRATE::feature::retry::RetryFeature`, ...). Trimming the feature set
+// without dropping them leaves a project that will not compile.
+function fullsetExcludes(paths: string[]): RegExp[] {
+  return (paths || []).map((p) => new RegExp(
+    '(^|/)' + String(p).replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '$'
+  ))
+}
+
+
+// Generate-time guard for the `src/feature/<name>/` layout (ts, js).
+//
+// Root renders one Feature component per ACTIVE feature, but Main then
+// copies the whole `tm/<lang>` tree — which puts a deactivated feature's
+// source straight back, silently undoing the filter. `target add` keeps
+// deactivated features out of `tm` in the first place; this covers the case
+// where a feature is switched off AFTER it was added.
+//
+// Only declared-but-inactive features are excluded. `base` and anything else
+// the model never mentions is left alone.
+function srcFeatureExcludes(model: any): RegExp[] {
+  const all = getModelPath(model, `main.${KIT}.feature`,
+    { required: false, only_active: false }) || {}
+  const active = getModelPath(model, `main.${KIT}.feature`,
+    { required: false }) || {}
+
+  return Object.keys(all)
+    .filter((name: string) => null == active[name])
+    .map((name: string) => new RegExp(
+      '(^|/)src/feature/' + name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '/'
+    ))
+}
+
+
+export type {
+  FeatureSource,
+}
+
+export {
+  featureOf,
+  availableFeatures,
+  findFeatureSources,
+  featureExcludes,
+  fullsetExcludes,
+  srcFeatureExcludes,
+}

package/src/helpers/naming.ts

@@ -209,16 +209,85 @@ function safeVarName(name: string, lang: string): string {
 }
 
 
+// Members the generated PHP SDK class already declares (see the php target's
+// fragment/Main.fragment.php). An entity accessor or backing field reusing one
+// is a FATAL redeclare — PHP will not parse the file, so the SDK yields zero
+// working tests rather than a degraded one.
+//
+// PHP method names are CASE-INSENSITIVE at declaration time, hence the
+// lowercased comparison: an entity `graph_ql` derives the accessor `GraphQl()`,
+// the same declaration as the SDK's own `graphql()`.
+//
+// This lives here, not in the php component, because the ACCESSOR NAME has to
+// agree across the SDK class and every doc/example component that calls it.
+// It did not: MainEntity_php emitted `Test_()` for an entity named `test`
+// while eight readme components emitted `Test()`, so the generated examples
+// called the static test-mode constructor and died with
+// "Call to undefined method <Name>SDK::load()".
+const PHP_SDK_METHODS = new Set([
+  'construct', '__construct', 'direct', 'get_root_ctx', 'get_utility',
+  'graphql', 'op_allowed', 'op_denied', 'options_map', 'prepare',
+  'raw_request', 'test',
+])
+
+// Backing fields the generated SDK object already holds, in EVERY target that
+// caches its entity accessors in `_<name>`. php spells it `$this->_utility`
+// and lua `self._utility`, but it is one hazard: the accessor's cache slot
+// silently aliases the SDK's own field, so `client:Utility()` hands back the
+// internal utility object and every entity method on it is nil.
+const SDK_FIELDS = new Set(['rootctx', 'utility', 'client', 'entctx'])
+
+
+/** The PHP accessor method for an entity: `$client-><Name>()`. */
+function phpEntityAccessor(Name: string): string {
+  return PHP_SDK_METHODS.has(String(Name).toLowerCase()) ? Name + '_' : Name
+}
+
+
+/**
+ * The backing field for an entity accessor's cache slot (`$this->_<name>`,
+ * `self._<name>`). Target-neutral: the colliding names are the SDK's own
+ * fields, which the targets share.
+ */
+function entityCacheField(name: string): string {
+  return SDK_FIELDS.has(String(name).toLowerCase()) ? name + '_' : name
+}
+
+
+// Symbols a doc example CALLS, which a same-named example variable would
+// shadow. The variable is syntactically fine; the example then fails at
+// RUNTIME, which is far harder to read than a compile error:
+//
+//   const consoles = await client.Console().list()
+//   for (const console of consoles) { console.log(console) }
+//   -> "console.log is not a function"   (nexarda, an API with a Console entity)
+//
+// Only languages where a plain variable can capture the symbol are listed.
+// php is absent on purpose: its variables carry a `$` sigil, so `$echo` can
+// never shadow `echo`.
+const EXAMPLE_GLOBALS: Record<string, string[]> = {
+  ts: ['console', 'process', 'globalThis'],
+  js: ['console', 'process', 'globalThis'],
+  py: ['print'],
+  rb: ['puts'],
+  lua: ['print'],
+  go: ['fmt'],
+}
+
+
 // A variable name for a doc EXAMPLE entity. Doc examples bind the SDK instance
 // to `client` (e.g. `const client = ...SDK.test()`), so an entity whose
 // lowercased name is also `client` — an API with a `Client` entity — would
 // shadow it: `const client = client.Client()...` is self-referential (TS2448/
 // TS7022) and breaks the readme_examples type-check. Append `_` to keep the
-// example variable distinct from the SDK instance. Also applies the normal
+// example variable distinct from the SDK instance. The same applies to any
+// symbol the example itself calls (EXAMPLE_GLOBALS). Also applies the normal
 // language-reserved-word guard.
 function exampleVarName(name: string, lang: string): string {
   const v = safeVarName(name, lang)
-  return 'client' === v ? v + '_' : v
+  if ('client' === v) return v + '_'
+  if ((EXAMPLE_GLOBALS[lang] || []).includes(v)) return v + '_'
+  return v
 }
 
 
@@ -256,6 +325,8 @@ export {
   isReservedName,
   safeVarName,
   exampleVarName,
+  phpEntityAccessor,
+  entityCacheField,
   isRbCoreConstant,
   rbSafeTypeName,
   isSwiftSdkType,

package/src/helpers/opExample.ts

@@ -20,6 +20,8 @@ import { each } from 'jostraca'
 import { canonKey } from './canonType'
 import { opRequestShape, entityIdField } from './opShape'
 
+import { phpEntityAccessor } from './naming'
+
 
 type ExampleLang = 'ts' | 'js' | 'py' | 'php' | 'rb' | 'lua' | 'go'
 
@@ -35,7 +37,19 @@ function litFor(lang: ExampleLang, type: any): string {
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'py' === lang ? 'True' : ('rb' === lang ? 'true' : 'true')
   if ('ARRAY' === k) return ('lua' === lang) ? '{}' : ('go' === lang ? '[]any{}' : '[]')
-  if ('OBJECT' === k) return ('go' === lang) ? 'map[string]any{}' : '{}'
+  // PHP has no `{}` literal — `["data" => {}]` is a parse error, which took
+  // the whole generated README down for any entity with an object-typed
+  // writable field (dymo-api-introduction, html-creator). Arrays serve as both
+  // list and map, so `[]` is the empty object too. Ruby and Lua likewise want
+  // their own empty-hash/table spelling rather than JS's.
+  if ('OBJECT' === k) {
+    if ('go' === lang) return 'map[string]any{}'
+    if ('php' === lang) return '[]'
+    if ('rb' === lang) return '{}'
+    if ('lua' === lang) return '{}'
+    if ('py' === lang) return '{}'
+    return '{}'
+  }
   return '"example"'
 }
 
@@ -154,7 +168,10 @@ function primaryOpCall(
   if ('go' === lang) { factory = `client.${eName}(nil)`; sep = '.' }
   else if ('lua' === lang) { factory = `client:${eName}()`; sep = ':' }
   else if ('rb' === lang) { factory = `client.${eName}`; sep = '.' }
-  else if ('php' === lang) { factory = `$client->${eName}()`; sep = '->' }
+  // php mangles an accessor that would collide with an SDK class member
+  // (see phpEntityAccessor); the example has to call the name that is
+  // actually declared, or it invokes the SDK's own method instead.
+  else if ('php' === lang) { factory = `$client->${phpEntityAccessor(eName)}()`; sep = '->' }
   else { factory = `client.${eName}()`; sep = '.' }
 
   // Argument string per op + language.

package/src/helpers/opShape.ts

@@ -127,6 +127,68 @@ type OpShapeItem = {
 // list-by-parent-id call failing because sibling routes' ids are demanded —
 // and steers callers into passing keys that flip runtime point dispatch to
 // the wrong route.)
+// The action names an op multiplexes, from its points' `select.$action`.
+//
+// A custom POST route like `/api/planet/{id}/terraform` is folded into the
+// `create` op as an alternative point, discriminated at call time by
+// `$action` in the data argument. The mechanism worked and was documented
+// NOWHERE — not in the README, not in the reference — so for an API with two
+// such routes, two of its six endpoints were unreachable by anyone using the
+// documented interface. Generated docs list them via this helper.
+function opActions(op: any): { action: string, path: string }[] {
+  const points: any[] = op && op.points ? each(op.points) : []
+
+  return points
+    .filter((pt: any) => null != (pt && pt.select && pt.select['$action']))
+    .map((pt: any) => ({
+      action: String(pt.select['$action']),
+      path: String(pt.orig || ''),
+    }))
+    .sort((a, b) => a.action < b.action ? -1 : a.action > b.action ? 1 : 0)
+}
+
+
+// True when any of the entity's ops multiplexes a custom action.
+function entityActions(entity: any): { op: string, action: string, path: string }[] {
+  const out: { op: string, action: string, path: string }[] = []
+
+  each(entity && entity.op).forEach((op: any) => {
+    opActions(op).forEach((a) => out.push({ op: op.name, ...a }))
+  })
+
+  return out
+}
+
+
+// The entity's own API path — the route a reader should recognise it by.
+//
+// NOT `points[0]` across every op flattened. Ops iterate in sorted-key order,
+// so `create` came first, and an entity whose create op folds in a custom
+// action (`/api/planet/{id}/forbid`) advertised THAT as its path. The
+// canonical route is the collection or record route, and never an action.
+function entityPath(entity: any): string {
+  const ops: any = (entity && entity.op) || {}
+
+  for (const opname of ['list', 'load', 'create', 'update', 'remove']) {
+    const op = ops[opname]
+    if (null == op) {
+      continue
+    }
+
+    const points: any[] = op.points ? each(op.points) : []
+    const canonical = points.filter((pt: any) =>
+      null == (pt && pt.select && pt.select['$action']))
+
+    const pick = (0 < canonical.length ? canonical : points)[0]
+    if (null != pick && null != pick.orig && '' !== pick.orig) {
+      return String(pick.orig)
+    }
+  }
+
+  return ''
+}
+
+
 function opParams(op: any): any[] {
   let points: any[] = op && op.points ? each(op.points) : []
 
@@ -533,6 +595,9 @@ export {
   entityCollection,
   opTypeName,
   opParams,
+  opActions,
+  entityActions,
+  entityPath,
   opRequestShape,
   entityIdField,
   entityDataIdField,

package/src/helpers/packageMeta.ts

@@ -38,15 +38,42 @@ function langLabel(target: string): string {
   return LANG_LABEL[target] || target
 }
 
-// GitHub org (publisher slug), repo name, and the canonical repo URLs.
+// Git host, org/repo path, and the canonical repo URLs.
+//
+// `<origin>/<slug>-sdk` is a DERIVATION, not a law. A project whose repo is
+// named anything else — `voxgig-sdk/voxgig-solardemo-sdk`, say, where the slug
+// is `solardemo` — used to have no way to say so, and got a `go.mod` module
+// path that 404s on `go get` plus `homepage`/`repository`/`bugs` URLs pointing
+// at a repo that does not exist. The only escape was renaming the slug, which
+// also renames the SDK classes: a public-API break, and no help at all to a
+// project that has already published.
+//
+//   main: kit: repo: {
+//     path: 'voxgig-sdk/voxgig-solardemo-sdk'   # overrides <origin>/<slug>-sdk
+//     host: 'github.com'                        # default
+//   }
 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}`
+
+  const declared = (model && model.main && model.main[KIT] && model.main[KIT].repo) || {}
+
+  const host = '' === (declared.host || '') ? 'github.com' : (declared.host || 'github.com')
+  const path = '' === (declared.path || '') ? `${origin}/${slug}-sdk` : String(declared.path)
+
+  // Last segment is the repo; everything before it is the org (which may
+  // itself contain slashes on hosts that allow subgroups, e.g. GitLab).
+  const seg = path.split('/')
+  const repo = seg[seg.length - 1]
+
+  const repoUrl = `https://${host}/${path}`
+
   return {
     slug,
     origin,
+    host,
+    // 'org/repo' — the path under the host, and the base of a go module path.
+    path,
     repo,
     repoUrl,
     issuesUrl: `${repoUrl}/issues`,
@@ -58,6 +85,94 @@ function repoInfo(model: any) {
 }
 
 
+// The go module path for a go-family target: the declared override, else the
+// repo path plus the target's subdirectory.
+//
+//   main: kit: target: go: module: path: 'github.com/acme/legacy-sdk/go'
+//
+// THE ONLY implementation. Twelve go components used to re-derive
+// `github.com/${origin}/${name}-sdk/go` inline, so fixing the path in one
+// place fixed nothing — and `ReadmeTop`, which prints the module in the root
+// README's package table, lives inside node_modules where a consumer cannot
+// patch it at all.
+function goModule(model: any, target: string): string {
+  const declared = model?.main?.[KIT]?.target?.[target]?.module?.path
+  if (null != declared && '' !== declared) {
+    return String(declared)
+  }
+
+  const { host, path } = repoInfo(model)
+  return `${host}/${path}/${target}`
+}
+
+
+// The SDK's OWN release version, for this target's manifest and release tag.
+//
+//   main: kit: target: ts: publish: version: '0.0.2'
+//
+// Defaults to '0.0.1' (the schema default), which is what every manifest
+// emitter used to HARDCODE. That is why regeneration reset a published
+// version: the value lived only in the generated output, so overwriting the
+// output threw it away, and a project that had shipped 0.0.2 silently got a
+// 0.0.1 manifest back. Declaring it in the model makes the manifest, the
+// install docs and the port's VERSION file agree, and survive.
+function packageVersion(model: any, target: string): string {
+  const declared = model?.main?.[KIT]?.target?.[target]?.publish?.version
+  return null != declared && '' !== declared ? String(declared) : '0.0.1'
+}
+
+
+// The Go language version for a go-family target's go.mod.
+//
+//   main: kit: target: go: module: goversion: '1.23'
+//
+// Defaults to 1.21, the release that introduced `log/slog` — which sdkgen's
+// own `log` feature template imports. The previous hardcoded `go 1.20` meant a
+// generated SDK could not compile the feature source sdkgen had just written
+// into it.
+function goVersion(model: any, target: string, fallback?: string): string {
+  const declared = model?.main?.[KIT]?.target?.[target]?.module?.goversion
+  if (null != declared && '' !== declared) {
+    return String(declared)
+  }
+  return fallback || '1.21'
+}
+
+
+// The root Go package IDENTIFIER — `package voxgigsolardemosdk`. Go requires
+// a plain identifier here, so unlike the module path it must be concatenated
+// from the slug rather than taken from the repo.
+//
+//   main: kit: target: go: module: package: 'acmesdk'
+//
+// The default concatenates `<origin><slug>sdk`, which DOUBLES the org prefix
+// whenever the slug already carries it: slug `voxgig-solardemo` under origin
+// `voxgig-sdk` produced `package voxgigvoxgigsolardemosdk`. A slug repeating
+// its org is the natural shape for a repo named `<org>-<product>`, so the
+// default now drops a leading origin prefix instead of restating it.
+//
+// This was the last of the four things the slug derives that had no override,
+// and the only one that came out wrong — see the identity note at the top of
+// model/sdkgen.aontu.
+function goPackageIdent(model: any, target: string): string {
+  const declared = model?.main?.[KIT]?.target?.[target]?.module?.package
+  if (null != declared && '' !== declared) {
+    return String(declared)
+  }
+
+  const ident = (s: string) => String(s || '').replace(/[^a-z0-9]/gi, '').toLowerCase()
+
+  const org = ident((model.origin || 'voxgig-sdk').replace(/-sdk$/, ''))
+  let slug = ident(model.name)
+
+  if ('' !== org && slug.startsWith(org)) {
+    slug = slug.slice(org.length)
+  }
+
+  return org + slug + 'sdk'
+}
+
+
 // 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
@@ -130,6 +245,25 @@ function packageName(model: any, eco: string): string {
   const origin = model.origin || 'voxgig-sdk'
   const base = origin.endsWith('-sdk') ? slug : `${slug}-sdk`
   const npmScoped = `@${origin}/${slug}${origin.endsWith('-sdk') ? '' : '-sdk'}`
+
+  // A target may name its published package outright — the escape hatch for a
+  // project whose registry name is not what the slug derives, and which cannot
+  // rename the slug without renaming its SDK classes:
+  //
+  //   main: kit: target: ts: publish: registry: package: '@acme/legacy-client'
+  //
+  // The key already existed in the schema ("registry package name ('' ->
+  // derived)") and was simply never read. Keyed by TARGET, so the ecosystem
+  // aliases ('npm', 'pypi', ...) resolve to the target that publishes to them.
+  const ECO_TARGET: Record<string, string> = {
+    npm: 'ts', pypi: 'py', gem: 'rb', luarocks: 'lua', composer: 'php',
+  }
+  const declared = model?.main?.[KIT]?.target?.[ECO_TARGET[eco] || eco]
+    ?.publish?.registry?.package
+  if (null != declared && '' !== declared) {
+    return String(declared)
+  }
+
   switch (eco) {
     case 'npm':
     case 'ts':
@@ -147,11 +281,11 @@ function packageName(model: any, eco: string): string {
     case 'php':
       return `${origin}/${base}`
     case 'go':
-      return `github.com/${origin}/${slug}-sdk/go`
+      return goModule(model, 'go')
     case 'go-cli':
-      return `github.com/${origin}/${slug}-sdk/go-cli`
+      return goModule(model, 'go-cli')
     case 'go-mcp':
-      return `github.com/${origin}/${slug}-sdk/go-mcp`
+      return goModule(model, 'go-mcp')
     // The notebook/analyst package layered on `py`. Distinct PyPI name so it
     // can version and publish independently of the SDK it wraps.
     case 'py-data':
@@ -214,11 +348,25 @@ 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).
+// A VALID uppercase env-var token: 'unsolicited-advice' -> 'UNSOLICITED_ADVICE'.
+//
+// THE ONLY WAY to build an env-var name segment. There used to be three
+// spellings of this in the components — `envToken(name)`,
+// `nom(x, 'NAME')` (the camel form uppercased, which SWALLOWS the hyphen) and
+// `x.name.toUpperCase().replace(...)` — and they agree only while the name has
+// no hyphen in it. A slug like `voxgig-solardemo` produced both
+// `VOXGIG_SOLARDEMO_TEST_LIVE` and `VOXGIGSOLARDEMO_TEST_LIVE` in the SAME
+// generated SDK: `test/utility.ts` read one, `PlanetEntity.test.ts` the other,
+// so setting either sent half the suite live and left the rest mocked — with
+// the suite reporting green either way.
+function envToken(name: any): string {
+  return String(name || '').toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '')
+}
+
+
+// The env-var base for this SDK: <NAME>_APIKEY, <NAME>_TEST_LIVE, ...
 function envName(model: any): string {
-  return String(model.name || '').toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '')
+  return envToken(model.name)
 }
 
 export {
@@ -240,4 +388,9 @@ export {
   nonAffiliation,
   keywords,
   envName,
+  envToken,
+  goModule,
+  goVersion,
+  goPackageIdent,
+  packageVersion,
 }