@voxgig/sdkgen 4.2.4 → 4.2.5

package/project/.sdk/src/cmp/swift/Main_swift.ts

@@ -1,6 +1,8 @@
 
 import * as Path from 'node:path'
 
+import { swiftTargetDir, swiftTestDir } from './utility_swift'
+
 import {
   cmp, each,
   File, Content, Copy, Folder, Fragment,
@@ -40,18 +42,51 @@ const Main = cmp(async function Main(props: any) {
 
   // Copy tm/swift files with replacements. `src/` holds only the per-feature
   // extension folders (not shipped into the SDK output).
+  // THE COPIED TREE HAS TO CARRY THE API NAME TOO.
+  //
+  // Copy substitutes file CONTENTS, never path components, so a blanket copy
+  // of tm/swift landed the runtime in a directory literally called
+  // ProjectNameSDK. Package.swift papered over it with an explicit `path:`,
+  // so it compiled and every swift suite passed — while every published SDK
+  // shipped `Sources/ProjectNameSDK/`, and SwiftPM's own convention
+  // (Sources/<target>) was broken in all of them.
+  //
+  // Copy's `to` prop names the destination, so the two placeholder subtrees
+  // are copied explicitly and the rest of tm/swift blanket-copied as before.
   Copy({
     from: 'tm/' + target.name,
-    exclude: [/src\//],
+    exclude: [/src\//, /Sources\//, /Tests\//],
     replace: {
       ...props.ctx$.stdrep,
       ProjectName: model.const.Name,
     }
   })
 
+  Folder({ name: 'Sources' }, () => {
+    Copy({
+      from: 'tm/' + target.name + '/Sources/ProjectNameSDK',
+      to: swiftTargetDir(model),
+      replace: {
+        ...props.ctx$.stdrep,
+        ProjectName: model.const.Name,
+      }
+    })
+  })
+
+  Folder({ name: 'Tests' }, () => {
+    Copy({
+      from: 'tm/' + target.name + '/Tests/ProjectNameSDKTests',
+      to: swiftTestDir(model),
+      replace: {
+        ...props.ctx$.stdrep,
+        ProjectName: model.const.Name,
+      }
+    })
+  })
+
   // Generated sources join the copied runtime under Sources/ProjectNameSDK.
   Folder({ name: 'Sources' }, () => {
-    Folder({ name: 'ProjectNameSDK' }, () => {
+    Folder({ name: swiftTargetDir(model) }, () => {
       Folder({ name: 'core' }, () => {
 
         // Main SDK client class, with entity accessors injected at the SLOT.

package/project/.sdk/src/cmp/swift/Package_swift.ts

@@ -1,4 +1,6 @@
 
+import { swiftTargetDir, swiftTestDir } from './utility_swift'
+
 import {
   Content,
   File,
@@ -14,10 +16,11 @@ import type {
 
 // Emits Package.swift (the SwiftPM manifest; the Swift twin of Package_go's
 // go.mod / Package_csharp's csproj). The library target compiles everything
-// under Sources/ProjectNameSDK (the copied runtime + generated sources); the
-// test target compiles Tests/ProjectNameSDKTests. Directory names are the
-// verbatim copied paths (Copy does not rewrite path components); the target
-// NAMES carry the API name.
+// under Sources/<Name>Sdk (the copied runtime + generated sources); the test
+// target compiles Tests/<Name>SdkTests. Both directories carry the API name:
+// Copy does not rewrite path components, so Main_swift copies the two
+// placeholder subtrees explicitly via Copy's `to` prop rather than letting a
+// blanket copy ship them as ProjectNameSDK.
 //
 // Dependencies: the runtime itself is dependency-free (Foundation + the
 // vendored struct), but declared target/feature deps flow into the manifest
@@ -91,11 +94,11 @@ let package = Package(
     targets: [
         .target(
             name: "${Name}Sdk",${targetdeps}
-            path: "Sources/ProjectNameSDK"),
+            path: "Sources/${swiftTargetDir(model)}"),
         .testTarget(
             name: "${Name}SdkTests",
             dependencies: ["${Name}Sdk"],
-            path: "Tests/ProjectNameSDKTests"),
+            path: "Tests/${swiftTestDir(model)}"),
     ]
 )
 `)

package/project/.sdk/src/cmp/swift/ReadmeExamplesTest_swift.ts

@@ -64,7 +64,7 @@ final class ReadmeExamplesTest: XCTestCase {
   // The three documents to scan, resolved relative to this test file.
   private func docs() -> [Doc] {
     let here = URL(fileURLWithPath: #filePath)
-      .deletingLastPathComponent()   // ProjectNameSDKTests
+      .deletingLastPathComponent()   // the test target dir
       .deletingLastPathComponent()   // Tests
       .deletingLastPathComponent()   // swift (module dir)
     let project = here.deletingLastPathComponent()  // project (holds root README)

package/project/.sdk/src/cmp/swift/ReadmeExplanation_swift.ts

@@ -1,4 +1,6 @@
 
+import { swiftTargetDir, swiftTestDir } from './utility_swift'
+
 import { cmp, Content } from '@voxgig/sdkgen'
 
 
@@ -24,16 +26,16 @@ generated for editor documentation.
 \`\`\`
 swift/
 ├── Package.swift                     -- SwiftPM manifest (zero runtime deps)
-├── Sources/ProjectNameSDK/
+├── Sources/${swiftTargetDir(model)}/
 │   ├── core/                         -- Main client, config, entity base, error type
 │   ├── entity/                       -- Generated entity clients
 │   ├── feature/                      -- Built-in features (Base, Test, Log, ...)
 │   ├── utility/                      -- Utility functions
 │   └── Struct/                       -- Vendored Voxgig Struct port
-└── Tests/ProjectNameSDKTests/        -- Test suites (XCTest)
+└── Tests/${swiftTestDir(model)}/    -- Test suites (XCTest)
 \`\`\`
 
-The main client class (\`${SDK}\`, under \`Sources/ProjectNameSDK/core\`)
+The main client class (\`${SDK}\`, under \`Sources/${swiftTargetDir(model)}/core\`)
 exposes the entity accessors. Reference entity or utility types directly only
 when needed. The SDK is dependency-free: JSON parsing is the vendored
 \`Struct/JSON.swift\`, HTTP transport is Foundation's \`URLSession\`, and the

package/project/.sdk/src/cmp/swift/Test_swift.ts

@@ -3,6 +3,8 @@ import type {
   ModelEntity
 } from '@voxgig/apidef'
 
+import { swiftTargetDir, swiftTestDir } from './utility_swift'
+
 import { cmp, each, Folder, entityCollection } from '@voxgig/sdkgen'
 
 
@@ -20,7 +22,7 @@ const Test = cmp(function Test(props: any) {
   // templates in tm/swift/Tests. Only the API-specific entity/direct tests
   // are generated here.
   Folder({ name: 'Tests' }, () => {
-    Folder({ name: 'ProjectNameSDKTests' }, () => {
+    Folder({ name: swiftTestDir(model) }, () => {
       const entity = each(entityCollection(model))
         .filter((e: any) => false !== e.active)
 

package/project/.sdk/src/cmp/swift/utility_swift.ts

@@ -132,10 +132,26 @@ function clean(o: any, dropDefaults?: boolean): any {
 }
 
 
+// SwiftPM's convention is Sources/<target>/ and Tests/<target>Tests/, and the
+// target is named <Name>Sdk in Package_swift. These name the two directories
+// so the copied runtime lands under the API's own name rather than under the
+// template's placeholder — see the note in Main_swift.
+function swiftTargetDir(model: any): string {
+  return model.const.Name + 'Sdk'
+}
+
+
+function swiftTestDir(model: any): string {
+  return swiftTargetDir(model) + 'Tests'
+}
+
+
 export {
   clean,
   projectPath,
   swiftPascalName,
+  swiftTargetDir,
+  swiftTestDir,
   swiftVarName,
   swiftString,
 }

package/project/.sdk/src/cmp/ts/Config_ts.ts

@@ -142,8 +142,11 @@ const Config = cmp(async function Config(props: any) {
           Line(` ${f.name}: ${nom(f, 'Name')}Feature,`)
         }),
 
+        // Rendered from configDefinition's def, not from f.config, so the
+        // literal carries the feature's `transport` role (station design
+        // §8.4) beside its options and cannot drift from the data rep.
         '// #FeatureConfigs': () => each(feature, (f: any) => {
-          Line(` ${f.name}: ${formatJson(f.config, { margin: 4 })},`)
+          Line(` ${f.name}: ${formatJson(configDef.feature[f.name], { margin: 4 })},`)
         }),
 
 

package/project/.sdk/src/cmp/ts/Main_ts.ts

@@ -4,7 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each, names, cmap,
   List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
-  entityClassName, entityCollection, srcFeatureExcludes,
+  entityClassName, entityCollection, srcFeatureExcludes, stationLibrary,
 } from '@voxgig/sdkgen'
 
 
@@ -106,6 +106,25 @@ if (fres instanceof Promise) { await fres }
             MainEntity(entprops)
           })
         })
+
+      // Station self-registration (station design §6.2 path 1;
+      // station-declarative-config §11 item 2): emitted ONLY when the model
+      // carries an ACTIVE station feature (installed via
+      // `package add @voxgig/sdkgen-station`). The library package name
+      // comes from the feature model's own `deps.ts` block — the same entry
+      // collectDeps flows into package.json — so the manifest dependency
+      // and the emitted require cannot disagree.
+      const stationPkg = stationLibrary(model, target.name)
+      if (null != stationPkg) {
+        Fragment({
+          from: Path.normalize(
+            __dirname + '/../../../src/cmp/ts/fragment/MainStation.fragment.ts'),
+          replace: {
+            ...props.ctx$.stdrep,
+            "'STATIONPKG'": JSON.stringify(stationPkg),
+          }
+        })
+      }
     })
 
     Config({ target })

package/project/.sdk/src/cmp/ts/fragment/MainStation.fragment.ts

@@ -0,0 +1,36 @@
+
+
+// Station self-registration (voxgig/station design §6.2, path 1): linking
+// this package is the whole bootstrap. When the station library is
+// installed beside this SDK, the {construct, config} factory pair is
+// registered under the api slug (config.main.slug, the descriptor slug) at
+// module init, so `station.sdk('<name>')` needs no imports in application
+// code. Registration is SOFT — the station library is a peer dependency of
+// the station feature, and a project without it skips registration and
+// gets exactly the SDK it always had. Only a genuine module-not-found is
+// swallowed: a station that RESOLVES but throws while loading must
+// propagate (a silently empty factory table has no visible cause), and so
+// must station_factory_conflict — two different builds of one SDK in one
+// process is not a thing to pick between quietly.
+let stationInstalled = true
+try { require.resolve('STATIONPKG') }
+catch (err: any) {
+  // MODULE_NOT_FOUND is the absent case. Anything else - an invalid
+  // package config, a root entry the package does not export - is a
+  // real failure to load a station that IS installed, and swallowing
+  // it would leave an empty factory table with no visible cause.
+  if ('MODULE_NOT_FOUND' !== err?.code) { throw err }
+  stationInstalled = false
+}
+
+if (stationInstalled) {
+  const { provide } = require('STATIONPKG')
+  // A station library predating the factory table has no provide() —
+  // there is nothing to register with, which is not this SDK's error.
+  if ('function' === typeof provide) {
+    provide(config.main.slug, {
+      construct: (options?: any) => new ProjectNameSDK(options),
+      config,
+    })
+  }
+}

package/project/.sdk/src/cmp/zig/Config_zig.ts

@@ -38,8 +38,10 @@ const Config = cmp(async function Config(props: any) {
   // representations render from the same `def`, so they cannot describe
   // different configs - and this target picks up `options.server` (the
   // OpenAPI server-variable defaults), which the hand-rolled build here
-  // omitted entirely.
-  const { def: config, json: configJson } = configDefinition(model)
+  // omitted entirely. Passing target.name opts this target into the main
+  // slug/version/target identity fields (read by station's descriptor -
+  // see configDefinition).
+  const { def: config, json: configJson } = configDefinition(model, target.name)
   const asData = isConfigData(configJson, configReprSetting(model))
 
   File({ name: 'config.' + target.ext }, () => {

package/project/sdkgen-package.json

@@ -3,7 +3,7 @@
     "package": 1
   },
   "name": "@voxgig/sdkgen",
-  "version": "4.2.4",
+  "version": "4.2.5",
   "provides": {
     "target": [
       "c",

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,
+}