@voxgig/sdkgen 4.2.3 → 4.2.5

package/src/cmp/AgentGuideTop.ts

@@ -83,19 +83,27 @@ package (other languages). Each target's guide documents its features.
 `)
     }
 
-    // Station paragraph (station design §9.4), only when the model
-    // carries the feature: an agent working on this repo should know
-    // the runtime story without leaving AGENTS.md.
+    // Station paragraph (station design §9.4; declarative design §11
+    // item 4), only when the model carries the feature: an agent working
+    // on this repo should know the runtime story without leaving
+    // AGENTS.md — and, first, that the application's integrations are
+    // DECLARED in station.json, so that file is where to look.
     if (features.some((f: any) => 'station' === f.name)) {
       Content(`**Station**: this SDK is a
 [voxgig/station](https://github.com/voxgig/station) plugin (the
-\`station\` feature, off by default). Bound to an open \`Station\`,
-the credential is resolved by sekreto under the plugin's secret name
+\`station\` feature, off by default). An application's outbound
+integrations are **declared in \`station.json\`** at its repo root —
+to learn what the application talks to, read that file: every SDK
+instance (\`sdk\`), per-api default (\`api\`), feature setting, and
+egress policy is declared there, and never a credential value.
+\`station.sdk('<name>')\` builds a declared instance on first ask;
+\`station.instances()\` lists them. Bound to an open \`Station\`,
+the credential is resolved by sekreto under the instance's secret name
 and injected at the transport seam — \`options()\` and
 \`prepare()\` output hold only a placeholder, so both are safe to
 inspect and log. \`station.tap(...)\`/\`station.events()\` show live
-traffic; \`station.plugins()\` lists descriptors. See the "Use with
-Station" README section and \`src/feature/station/\` (or the
+traffic; \`station.plugins()\` lists live descriptors. See the "Use
+with Station" README section and \`src/feature/station/\` (or the
 target's feature container) for the generated adapter.
 
 `)

package/src/cmp/ReadmeStation.ts

@@ -6,20 +6,39 @@ import {
   getModelPath
 } from '../types'
 
-import { envName } from '../helpers/packageMeta'
+import { envName, packageName } from '../helpers/packageMeta'
 
 
 // The "Use with Station" README section (station design §9.4): rendered
 // ONLY when the project's model carries the station feature (installed
 // via `package add @voxgig/sdkgen-station`) — a project without it sees
-// nothing. Documents the binding forms and the secret name; store
-// configuration is sekreto's documentation, deliberately not restated
-// here (one canonical source).
+// nothing. Leads with the DECLARATIVE flow — a `station.json` block and
+// `station.sdk()` (declarative design §11 item 3) — keeps the imperative
+// `connect()` form as the retrofit path, and documents the
+// instance-derived secret/env-var name (declarative design §3.4, §5.1:
+// the same envtoken grammar as sdkgen's envName, applied to the INSTANCE
+// name, so the untagged instance keeps the env var this README already
+// documents to the byte). Store configuration is sekreto's
+// documentation, deliberately not restated here (one canonical source);
+// the error codes live in sdkgen's one catalog page, linked rather than
+// restated for the same reason.
 
 // Targets where station.connect(SDK) is the idiomatic binding; everything
 // else uses inverted binding through the SDK's own constructor.
 const CONNECT_TARGETS = ['ts', 'js', 'py', 'rb', 'php', 'lua', 'perl']
 
+// Targets whose module system has an init hook that actually runs
+// (station design §6.2 path 1): there, linking the generated package
+// fills the process-global factory table and `station.sdk()` needs no
+// application code. Everywhere else the README must say
+// `Station.provide` (path 2) plainly rather than imply an import is
+// enough — a Java import is a compile-time alias that runs nothing.
+const SELF_REGISTER_TARGETS =
+  ['ts', 'js', 'go', 'py', 'rb', 'php', 'lua', 'perl', 'elixir', 'clojure']
+
+const ERROR_CATALOG_URL =
+  'https://github.com/voxgig/sdkgen/blob/main/docs/reference/station-errors.md'
+
 const ReadmeStation = cmp(function ReadmeStation(props: any) {
   const { target } = props
   const { model } = props.ctx$
@@ -30,9 +49,15 @@ const ReadmeStation = cmp(function ReadmeStation(props: any) {
     .find((f: any) => 'station' === f?.name)
   if (null == station) { return }
 
+  // The descriptor slug is the model's hyphenated name (carried as
+  // main.slug in the embedded config); an untagged instance ref IS the
+  // slug, so this is also the default instance name.
+  const slug = model.name
   const env = envName(model)
-  const secretname = env.toLowerCase() + '.apikey'
+  const secretbase = env.toLowerCase()
+  const secretname = secretbase + '.apikey'
   const connect = CONNECT_TARGETS.includes(target.name)
+  const selfreg = SELF_REGISTER_TARGETS.includes(target.name)
 
   Content(`
 ## Use with Station
@@ -42,24 +67,79 @@ plugin: bind it to a local \`Station\` and outbound configuration,
 credentials, and observability move to one place. The feature is
 present but **off by default** — nothing changes until you bind.
 
+### Declarative: \`station.json\` + \`station.sdk()\`
+
+Declare an instance in \`station.json\` at the repo root (committable —
+names and stores, never values):
+
+\`\`\`json
+{ "station": 1,
+  "profiles": { "default": {
+    "sdk": { "${slug}": {${selfreg ?
+      `\n      "package": "${packageName(model, target.name)}"` : ''} } } } } }
+\`\`\`
+
+Then get the client where you need it:
+
+1. \`station = Station.open()\` — reads and validates \`station.json\`;
+   constructs nothing.
+2. \`client = station.sdk('${slug}')\` — built on first ask and cached,
+   so the same name returns the same client.
+
+${selfreg
+  ? `Loading this package is the whole bootstrap: it registers its own
+factory (constructor plus embedded config) with the station library at
+module init, so \`station.sdk()\` needs no SDK import in application
+code. That is what the \`package\` key above is for — it names the module
+for station to load, since nothing else in this example would execute
+it. An application that imports this SDK for its types anyway can drop
+the key: that import is itself the bootstrap.`
+  : `In this language an import runs no code, so register the factory
+once at startup — \`Station.provide('${slug}', ...)\`, one line — and
+every other line of configuration stays in \`station.json\`.`}
+
+A second instance of the same API is one more key — \`"${slug}$test"\`
+beside \`"${slug}"\` — and \`station.sdk('${slug}$test')\` returns it.
+SDK features are configured in the same file too: fleet-wide, per api,
+or per instance. \`station.check()\` resolves and constructs every
+active instance without sending a request — run it in CI.
+
+### The secret name derives from the instance
+
+The credential comes from [sekreto](https://github.com/voxgig/sekreto)
+under a name derived from the **instance** name — the instance token
+lowercased, plus \`.apikey\`. The untagged instance \`${slug}\` derives
+\`${secretname}\` — by default the \`${env}_APIKEY\` environment
+variable this README already documents, unchanged. A tagged instance
+derives its own: \`${slug}$test\` → \`${secretbase}_test.apikey\` →
+\`${env}_TEST_APIKEY\` — each instance is a separate credentialed use
+of the API, and its env var is derivable from the name you chose. To
+pin a name instead, set \`secret\` on the instance block, or at the
+api level for several instances sharing one key. Point a profile at a
+vault later and application code does not change; sekreto's own
+documentation covers the stores. The key stays out of \`options()\` and
+\`prepare()\` output; \`station.tap(...)\` shows live traffic.
+
+### Imperative: ${connect ? '`connect()`' : 'inverted binding'} — the retrofit path
+
 ${connect
   ? `Bind by passing the SDK class to the station:
 
 1. \`station = Station.open()\` — profile, env, and proxy all defaulted.
 2. \`client = station.connect(${model.const.Name}SDK)\` — replaces direct
-   construction.`
+   construction; \`connect(${model.const.Name}SDK, { as: 'test' })\` binds
+   a second, tagged instance.`
   : `Bind through the constructor this SDK already has (inverted
 binding): open a station, then construct with station-built options —
 \`station.options()\` merges the handle, the activation entry, and the
 correct feature order into the plain options the constructor accepts.`}
 
-The credential comes from [sekreto](https://github.com/voxgig/sekreto)
-under the name \`${secretname}\` — by default the \`${env}_APIKEY\`
-environment variable this README already documents, unchanged. Point a
-profile in \`station.json\` at a vault later and application code does
-not change; sekreto's own documentation covers the stores. The key
-stays out of \`options()\` and \`prepare()\` output; \`station.tap(...)\`
-shows live traffic.
+With no \`station.json\` at all this runs solo with everything
+defaulted — the two-line form is how an existing application starts.
+
+Station failures surface through this SDK's own error path
+(\`err.code\`, \`station_*\`); the codes are catalogued in
+[station error codes](${ERROR_CATALOG_URL}).
 `)
 })
 

package/src/helpers/station.ts

@@ -0,0 +1,80 @@
+// The station SELF-REGISTRATION seam (station design station.md §9 /
+// station-declarative-config.md §6.2 path 1, §11 item 2): when the station
+// feature is installed and active, the generated MAIN module registers the
+// SDK's `{construct, config}` factory pair with the station library at
+// module init, so `station.sdk('<name>')` needs no imports in application
+// code. The registration key is the descriptor slug — `config.main.slug`,
+// the same field station's `normalizeDescriptor` reads — so the generated
+// code passes the embedded config's own value rather than re-deriving it.
+//
+// This helper answers the ONE question every Main_<lang> asks before
+// emitting that registration: is the station feature ACTIVE in this model,
+// and what is the station library package for this target? Both come from
+// the model — the active-filtered feature map (exactly the view the Main
+// components already emit from) and the station feature's own
+// `deps.<target>` block, which is the same entry `collectDeps` flows into
+// the generated manifest. ONE RULE, ONE PLACE: reading the package name
+// here, never hardcoding it per language, means the manifest dependency
+// and the emitted require can not disagree.
+//
+// Returns undefined when the station feature is absent, inactive, or
+// declares no active station library dep for this target (the vendored
+// targets carry the library inside their tm overlay instead of as a dep —
+// station.md §9.2): no dep, no package to require, no registration to emit.
+
+import { each } from 'jostraca'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { SdkGenError } from '../utility'
+
+import type { SdkModel, ModelFeature } from '../types'
+
+
+function stationLibrary(model: SdkModel, targetName: string): string | undefined {
+  // Active-filtered on purpose: an inactive feature ships no source, no
+  // embedded config entry and no manifest dep, so it must emit no
+  // registration either.
+  const feature = getModelPath(model, `main.${KIT}.feature`,
+    { required: false }) || {}
+
+  const station: ModelFeature | undefined = feature.station
+  if (null == station) { return undefined }
+
+  const deps = station.deps?.[targetName]
+  if (null == deps) { return undefined }
+
+  // Feature deps count only when explicitly active — collectDeps semantics,
+  // so the require target is exactly the set the manifest carries.
+  const names = each(deps)
+    .filter((dep: any) => true === dep?.active)
+    .map((dep: any) => dep?.key$)
+    .filter((name: any) => null != name && '' !== name)
+
+  if (0 === names.length) { return undefined }
+
+  // EXACTLY ONE, or say so. Picking the first of several — each() sorts,
+  // so it would be the alphabetically first — means the generated main
+  // can `require` an unrelated helper package, find no `provide`, and
+  // leave the factory table silently empty. The station feature model
+  // declares one library per target; a second active dep is a model
+  // question only its author can answer.
+  if (1 < names.length) {
+    throw new SdkGenError(
+      'station: feature `station` declares ' + names.length + ' active ' +
+      'dependencies for target `' + targetName + '` (' +
+      names.map(String).sort().join(', ') + '), so the station library to ' +
+      'register with is ambiguous. Declare exactly one active dep per ' +
+      'target in the feature model, or mark which one is the library.')
+  }
+
+  return String(names[0])
+}
+
+
+export {
+  stationLibrary,
+}

package/src/sdkgen.ts

@@ -73,6 +73,7 @@ import {
   srcFeatureExcludes,
 } from './helpers/featureSource'
 import type { FeatureSource } from './helpers/featureSource'
+import { stationLibrary } from './helpers/station'
 import {
   definitionPath,
   definitionFolder,
@@ -299,7 +300,13 @@ function SdkGen(opts: SdkGenOptions) {
     // so resolve it ONCE: every destination is compared against it, and a
     // comparison between a relative and an absolute path is meaningless.
     const root = Path.resolve(folder)
-    const external = externalItems(model, root, ['target', 'docs'])
+    // Snapshot the decision before preflight. In particular, do not check a
+    // missing optional destination once for safety and AGAIN before writing:
+    // if it appeared between those checks, the pass could write into content
+    // that was never ownership-validated.
+    const external: ExternalPlan[] =
+      externalItems(model, root, ['target', 'docs'])
+        .map((ext) => ({ ...ext, skip: externalSkipReason(ext, fs) }))
 
     // Before ANY file is written, in-tree included: a destination that turns
     // out to be wrong must abort the whole generation, not leave half of it
@@ -382,17 +389,13 @@ function SdkGen(opts: SdkGenOptions) {
     }
 
     for (const ext of external) {
-      // `active: false` is the project's only lever to stop the generator
-      // writing into a repo it does not own, so it has to be honoured HERE —
-      // the consumer Root iterates targets raw and does not check it. The
-      // target is still removed from the in-tree model above (withoutExternal
-      // takes every `output: path` target, active or not), so switching one
-      // off generates it nowhere rather than relocating it into
-      // `<sdk-repo>/<target>/`.
-      if (!ext.active) {
+      // A skipped external target is still removed from the in-tree model
+      // above: neither `active: false` nor a missing `output.create: false`
+      // destination may relocate it into `<sdk-repo>/<target>/`.
+      if (null != ext.skip) {
         log.info({
           point: 'generate-external-skip', target: ext.name, folder: ext.folder,
-          note: ext.name + ' inactive, not generated'
+          note: ext.skip
         })
         continue
       }
@@ -673,6 +676,13 @@ type ExternalSpec = {
 }
 
 
+type ExternalPlan = ExternalSpec & {
+  // Snapshotted before destination validation and consumed unchanged by the
+  // generation loop, so a filesystem race cannot bypass the safety guard.
+  skip: string | null
+}
+
+
 // Targets declaring `output: path` — generated into their own repo rather
 // than into `<sdk-repo>/<target>/`.
 //
@@ -715,6 +725,32 @@ function externalItems(
 }
 
 
+// Why this external item should not get a generation pass RIGHT NOW.
+//
+// `active: false` disables the target itself. `output.create: false` does
+// something deliberately narrower: the target stays active in the model but
+// an absent destination is treated as an optional checkout rather than a
+// folder sdkgen should fabricate. If that repo is checked out later, the same
+// unchanged model generates it normally.
+//
+// Snapshotted into ExternalPlan because both the pre-write destination guard
+// and the actual pass must make the identical decision. If the guard skipped
+// an item that the pass did not, generation could write outside the project
+// without any of the ownership checks below.
+function externalSkipReason(ext: ExternalSpec, fs: any): string | null {
+  if (!ext.active) {
+    return ext.name + ' inactive, not generated'
+  }
+
+  if (false === ext.target.output?.create && !fs.existsSync(ext.folder)) {
+    return ext.name + ' output folder does not exist and ' +
+      'output.create=false, not generated'
+  }
+
+  return null
+}
+
+
 // The `.jostraca` bookkeeping tree (meta log + a duplicate of the last
 // generated output) that jostraca leaves at an output root. It is the only
 // on-disk evidence that this toolchain has generated into a directory
@@ -754,14 +790,14 @@ const EXTERNAL_MARKER = '.jostraca'
 // generating somewhere other than it believes must be told. A destination
 // that legitimately holds other content first (a repo seeded with a README
 // and LICENCE) says so once in the model, with `output: adopt: true`.
-function checkExternalFolders(external: ExternalSpec[], root: string, fs: any) {
+function checkExternalFolders(external: ExternalPlan[], root: string, fs: any) {
   const claimed: Record<string, string> = {}
 
   for (const ext of external) {
-    // An inactive target writes nothing, so its destination is not a hazard —
-    // and switching a target off must not require keeping its now-unused
-    // path valid.
-    if (!ext.active) continue
+    // A skipped item writes nothing, so its destination is not a hazard. The
+    // snapshotted decision gates the actual pass too; keeping it identical is
+    // what makes the pre-write check complete.
+    if (null != ext.skip) continue
 
     const label = ext.kind.charAt(0).toUpperCase() + ext.kind.slice(1)
 
@@ -1107,6 +1143,7 @@ export {
   featureExcludes,
   fullsetExcludes,
   srcFeatureExcludes,
+  stationLibrary,
 
   definitionPath,
   definitionFolder,

package/src/types.ts

@@ -47,6 +47,11 @@ type ModelFeature = NameCases & {
   active?: boolean
   title?: string
   version?: string
+  // Transport role (station design §8.4): 'base' replaces the transport
+  // slot (only `test`), 'wrap' wraps it, 'none' is hook-only. Schema
+  // default is 'none'; configDefinition carries it into the embedded
+  // config beside the feature's `config.options`.
+  transport?: string
   hook?: Record<string, ModelHook>
   deps?: Record<string, Record<string, ModelDep>>
   [extra: string]: any
@@ -71,6 +76,7 @@ type ModelTarget = NameCases & {
   output?: {
     path?: string
     repo?: string
+    create?: boolean
     adopt?: boolean
     sdkrel?: string
   }

package/src/utility.ts

@@ -318,7 +318,21 @@ function configDefinition(model: any, targetname?: string): { def: any, json: st
 
   const featureDefs: any = {}
   each(feature, (f: any) => {
-    featureDefs[f.name] = f.config || {}
+    // The feature's declared config (its `options` key set with typed
+    // defaults) PLUS its transport role (station design §8.4): 'base'
+    // replaces the transport slot, 'wrap' wraps it, 'none' is hook-only.
+    // Station's descriptor (normalizeDescriptor in voxgig/station) reads
+    // `transport` beside `options` to validate the resolved feature order.
+    // The role is DECLARED in the feature model, never inferred - an empty
+    // `hook: {}` is wrong for station, which both wraps and dispatches
+    // hooks. Additive: a model unified without the schema's `transport`
+    // default simply omits the key, which station tolerates by degrading
+    // its role checks to nothing.
+    const fdef: any = { ...(f.config || {}) }
+    if (null != f.transport && '' !== f.transport) {
+      fdef.transport = String(f.transport)
+    }
+    featureDefs[f.name] = fdef
   })
 
   const options: any = { base: baseUrl }