@voxgig/sdkgen 4.20.0 → 4.22.0

package/model/sdkgen.aon

@@ -5,44 +5,15 @@ main: def: {
 }
 
 
-# Canonical order for language targets in generated documentation
-# (top-level README, per-language docs links). Targets present in the
-# SDK but not listed here are appended afterwards in spec-defined
-# order. Override per-SDK by setting
-# `main.kit.config.docs_order: ['py','ts',...]` in
-# `<sdk>/.sdk/model/config.aontu`.
 main: kit: config: docs_order: *['ts','py','php','go','rb','lua'] | [&: string]
 
-# How the API model is embedded in a generated SDK (design rung L1).
-#
-#   auto     by size - data above the threshold, literal below (the default)
-#   literal  always a composite literal, whatever the size
-#   data     always a parsed JSON constant, whatever the size
-#
-# Declared as a closed set so a typo is REJECTED at model-compile time rather
-# than silently falling through to `auto`, which would quietly restore the
-# compile cost this exists to remove.
 main: kit: config: repr: *'auto' | 'literal' | 'data'
 
-# How the generated test suites behave.
 main: kit: test: {
 
   live: {
-    # Assert live request outcomes, while continuing independent work.
-    # Explicit false retains the legacy exploratory direct-test policy.
-    # Per-target overrides remain available for migration.
     strict: *true | boolean
 
-    # The base URL a live run points at. '' derives it from the spec's first
-    # declared server, but ONLY when that is a loopback address.
-    #
-    # For an OpenAPI-derived model `servers[0].url` is the PRODUCTION host of
-    # a third-party API, and a generated live suite runs under `npm test` on
-    # every CI push. Inferring the base from the spec therefore pointed CI at
-    # a stranger's API — unauthenticated, on three operating systems, on every
-    # push — and pointed the generated write scripts there too. A live target
-    # is now taken only when it is unambiguously ours: declared here, or
-    # loopback, which nobody else can be behind.
     base: *'' | string
 
     # Whether the SDK's own repo ships a runnable companion server under
@@ -55,71 +26,14 @@ main: kit: test: {
 }
 
 
-# ---------------------------------------------------------------------------
-# SDK IDENTITY
-#
-# The root `name` slug is FOUR different things wearing one name. Each is
-# derived from the slug by default; each can differ, and in practice does:
-#
-#   1. IDENTIFIERS   class names (AcmeSDK, AcmeError), entity classes, the Go
-#                    root package identifier, the test env-var prefix.
-#                    Source: `name`. No override — this IS what the slug is.
-#
-#   2. SOURCE        where the code lives: the repo URL, and the base of the
-#                    Go module path.        -> main: kit: repo: path
-#
-#   3. PUBLISHED     what a consumer installs: the npm/PyPI/... package name.
-#                    -> main: kit: target: <t>: publish: registry: package
-#
-#   4. GO PACKAGE    the `package x` identifier in the generated Go root file.
-#                    -> main: kit: target: <t>: module: package
-#
-# Conflating them is not theoretical. A project whose repo was named
-# `<org>-<product>-sdk` rather than `<slug>-sdk` had only one lever — rename
-# the slug — and renaming it to fix (2) silently renamed (1), doubled the org
-# prefix in (4) (`package voxgigvoxgigsolardemosdk`), and would have orphaned
-# (3) had the package already been published. Each override below exists
-# because a real project needed those four values to differ.
-#
-# Set `name` to what the SDK IS. Override the other three when the world
-# disagrees with the derivation.
-# ---------------------------------------------------------------------------
-
-# Where this SDK's source repository lives.
-#
-# `<origin>/<name>-sdk` is only the DEFAULT. A project whose repo is named
-# anything else had no way to say so, and got a go 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 `name`, which also renames the SDK
-# classes — a public-API break, and no help to a project already published.
+
 main: kit: repo: {
-  # '<org>/<repo>' under the host. '' -> '<origin>/<name>-sdk'.
   path: *'' | string
 
   host: *'github.com' | string
 }
 
 
-# WHO WROTE THIS PACKAGE — the manifest's `author` and `contributors`.
-#
-# Generated output is overwritten, so attribution hand-edited into a
-# package.json is silently DELETED on the next regeneration. That is exactly
-# what happened the first time the seneca-provider target regenerated a
-# hand-written provider repo: the manifest's author and its two named
-# contributors were dropped, and nothing failed to warn about it — credit is
-# not something a build can miss.
-#
-# So it is declared here, like every other value a project owns about itself.
-# Unset means the PUBLISHER (Voxgig), which is what a generated SDK carries
-# and what a project that has never thought about it should get.
-#
-#   main: kit: author: { name: 'Ada Lovelace', url: 'https://example.com' }
-#   main: kit: contributor: 'ada': { name: 'Ada Lovelace', url: '...' }
-#
-# `contributor` is a MAP, not a list, because aontu unifies maps by key: a
-# project can add one contributor without restating the others, and a
-# duplicate key is a conflict rather than a silent second entry. Emitters
-# render it in sorted-key order, so the manifest is byte-stable.
 main: kit: author: {
   name: *'' | string
   url: *'' | string
@@ -131,59 +45,12 @@ main: kit: contributor: &: {
 }
 
 
-# PROVENANCE: where a copied target or feature came from.
-#
-# `target add` / `feature add` copy a shipped definition into a project and
-# stamp these three keys into the copy, by rewriting the `base: 'BASE'` line
-# the shipped file carries as an anchor:
-#
-#   base      the `.sdk` folder the copy came from, relative to the project
-#             (absolute only for an out-of-tree source). '/'-normalised, so a
-#             project resynced on Windows and on Linux records the same value.
-#   origname  the name in the SOURCE, when installed under a different one
-#             (`target add go~go2` -> origname 'go'). Empty when they match.
-#   package   the sdkgen package that provided it, when the source declared
-#             one. Empty otherwise.
-#
-# Read by `feature add` (to find each target's template tree) and by `doctor`
-# (to re-resolve the scaffold a copy should be compared against). Without
-# them both fall back to the bundled scaffold, which is right only while
-# everything ships inside @voxgig/sdkgen.
-#
-# DEFAULTED, deliberately. A bare `string` inside a `&:` spread makes the key
-# REQUIRED, which would fail the model compile of every project whose copies
-# predate this — and `origname`/`package` are stamped only when they apply,
-# so it would fail every ordinary install too. `*''` also keeps them FALSY
-# when unset, which is what the two readers already test for.
 main: kit: target: &: {
   name: key()
   active: *true | boolean
   ext: string
   comment: line: string
 
-  # APPLICABILITY (docs/design/feature-tags.md). What this target can offer
-  # a feature; a feature applies here when its `needs` is a subset of this.
-  # Empty is the default, so a target says nothing until it has a reason to.
-  #
-  # THE VOCABULARY IS CLOSED — extended by editing this comment and the
-  # schema, never by a package inventing a string. Two authors spelling the
-  # same capability differently is the whole failure mode a free-form tag
-  # would reintroduce.
-  #
-  #   sekreto   a vendored sekreto port lives in this target's feature
-  #             container, so a feature can resolve secrets through it
-  #
-  #   schema    this target emits the generated `Schema` module — the
-  #             model's option spec and per-entity struct.validate specs —
-  #             so a feature can validate against the model's own types
-  #
-  # Tags named in the design note but not yet load-bearing
-  # (`per-feature-file`, `deps`, `transport-wrap`, `hooks`, `delegates`)
-  # are deliberately absent until a feature actually gates on one: a tag
-  # whose answer is currently "everyone" buys nothing and has to be kept
-  # true across 27 targets.
-  #
-  # A map keyed by tag, matching `needs` — see the note there.
   provides: &: boolean
 
   base:     *'' | string
@@ -197,19 +64,8 @@ main: kit: target: &: {
     # cannot be derived — e.g. a repo whose name is not '<slug>-sdk'.
     path: *'' | string
 
-    # Go family only. The root package IDENTIFIER — `package acmesdk` — not
-    # an import path. Go requires a plain identifier here, so it is
-    # concatenated from the slug rather than taken from the repo.
-    #
-    # '' derives '<origin><slug>sdk', dropping a leading origin prefix the
-    # slug already carries: slug 'voxgig-solardemo' under origin 'voxgig-sdk'
-    # gives 'voxgigsolardemosdk', not 'voxgigvoxgigsolardemosdk'.
     package: *'' | string
 
-    # Go family only. The `go` directive written into go.mod. Defaults to
-    # 1.21 — the release that introduced `log/slog`, which sdkgen's own
-    # `log` feature template imports. go-cli and go-mcp carry higher
-    # floors imposed by their dependencies.
     goversion: *'' | string
   }
   # WHO WROTE THIS PACKAGE, when it differs from the model-wide
@@ -227,196 +83,49 @@ main: kit: target: &: {
     version: *'*' | string
   }
 
-  # Generated files this target NO LONGER writes - the runner a template
-  # retirement superseded, an old vendored-library shape. jostraca writes
-  # and never deletes, so retiring a template leaves the old generated
-  # file behind in every consumer, beside its replacement: two copies of
-  # the same machinery, one of them stale. Paths are relative to the
-  # target's OUTPUT directory. `doctor` reports any that still exist;
-  # `doctor prune` deletes them - the one write doctor performs, and only
-  # ever of files this list names.
   superseded: *[] | [&: string]
 
-  # How `target add` trims this target's feature source down to the
-  # features the model actually selects. Where that source LIVES is
-  # discovered by walking the template tree (helpers/featureSource), so
-  # nothing here describes layout — this is only about what a target can
-  # survive having removed.
   feature: {
-    # Whether the feature set may be trimmed at all. A target whose
-    # templates statically reference every shipped feature from a file
-    # that cannot simply be dropped (zig's `root.zig`, scala's
-    # `SdkTestMain.scala`) must say false until those files are driven
-    # from the model — otherwise a trimmed project will not compile.
     trim: *true | boolean
 
-    # Templates that only compile with the COMPLETE feature set, as paths
-    # relative to the target template root. These are the cross-feature
-    # test suites: they construct every shipped feature type by name, so a
-    # trimmed project drops them along with the features they exercise.
-    # A project carrying the full set keeps them.
     fullset: *[] | [&: string]
   }
 
-  # Publication: how (and whether) this port is released. Credentials are
-  # always injected by the aql key vault (never on disk or argv).
-  #
-  # Every port gets a git release tag `<prefix>/vX.Y.Z` (prefix defaults
-  # to the target name). Ports with a `registry` entry also publish a
-  # package to that registry — but only when the registry is active
-  # (`registry.state === 'active'`): registries are activated one at a
-  # time as each ecosystem is ready. Until then a port is 'pending'
-  # (declared + git-tag-published, but not yet uploaded to the registry).
-  # Tag-only ports (the go family: the Go proxy resolves from GitHub
-  # tags) simply leave `registry` unset — they are implicitly pending
-  # until their `<target>/vX.Y.Z` tag exists.
-  # WHERE this target's files are written.
-  #
-  # Empty (the default) means the ordinary place: `<sdk-repo>/<target>/`,
-  # a folder inside the SDK repo, which is what every language target wants.
-  #
-  # A target that generates a SEPARATE, independently released package needs
-  # somewhere else. The Seneca provider is the case: it is its own npm
-  # package in its own repo (`@seneca/<name>-provider`), depends on the ts
-  # SDK as a normal published dependency, and carries a repo's worth of
-  # furniture — LICENSE, CI workflow, doc/ — that must not land inside the
-  # SDK repo.
-  #
-  # Relative paths resolve against the SDK repo root, so a sibling checkout
-  # is `'../<repo>'`. Absolute paths are taken as given.
-  #
-  # Files are written at the ROOT of that path, NOT under a `<target>/`
-  # subfolder: the destination IS the package.
-  #
-  # Generation into it is a SEPARATE pass, so the repo receives only what
-  # this target emits — none of the SDK repo's own root files (README,
-  # AGENTS.md, the build scaffold) follow it out.
   output: {
     path: *'' | string
 
-    # Whether generation may create a destination folder that does not yet
-    # exist. true preserves the ordinary behaviour: jostraca creates it and
-    # any missing parents. false keeps the target active but skips its
-    # out-of-tree generation pass until the destination folder exists — for
-    # example when a separate provider fleet is only checked out on some
-    # machines. An existing destination still goes through every ownership
-    # and overwrite-safety check below.
     create: *true | boolean
 
-    # Write into a destination that already holds content this generator did
-    # not write.
-    #
-    # Generation OVERWRITES, jostraca creates missing parent directories, and
-    # the path is taken verbatim from the model — so a typo ('.', '..', a
-    # target name) fabricates a package tree somewhere arbitrary, or replaces
-    # an unrelated repo's package.json, README, LICENSE and CI workflow in
-    # place. Generation therefore refuses a destination that is neither
-    # absent, nor empty, nor carrying the `.jostraca` bookkeeping a previous
-    # generation left there.
-    #
-    # A repo seeded with its own README/LICENCE before the first generation
-    # is the legitimate case that trips the guard. Say so here, once: the
-    # point is that the destination is a DECISION, not a typo.
     adopt: *false | boolean
 
-    # The path from the destination BACK to the SDK project — what the
-    # target's own docs, scripts and live tests name when they reach for
-    # something the SDK repo distributes only in source (the companion test
-    # server in `app/`).
-    #
-    # '' derives it by inverting the resolved `path`, which is exact only
-    # while the walk back crosses nothing this model names — true for
-    # '../<repo>', false for anything ascending further. A project declaring
-    # '../../seneca/solardemo-provider' derived
-    # '../../voxgig-sdk/voxgig-solardemo-sdk', where `voxgig-sdk` is the name
-    # of the WORKSPACE DIRECTORY holding the checkout on ONE machine — and
-    # that string is committed into the destination's README and test files,
-    # so the next developer's layout regenerates a spurious diff and an
-    # instruction path that is wrong for everyone else. Declare it here when
-    # the destination is more than one level away; generation warns until you
-    # do.
     sdkrel: *'' | string
 
-    # '<org>/<repo>' for the repo the files land in, under `main: kit: repo:
-    # host`. A target generating out of tree is usually released from that
-    # repo too, so its manifest's homepage/repository/bugs must point there
-    # and NOT at the SDK's own repo, which is what they would otherwise
-    # derive from.
-    #
-    # '' lets the target decide: a target that knows its convention (the
-    # Seneca provider's is `senecajs/seneca-<name>-provider`) supplies its
-    # own default, and falls back to the SDK's repo when it has none.
     repo: *'' | string
   }
 
   publish: {
-    # The SDK's OWN release version — what the generated manifest declares
-    # and what the port's Makefile tags (`<target>/v<version>`).
-    #
-    # Generated output is overwritten, so a version hand-edited into
-    # package.json / pyproject.toml / VERSION is lost on the next
-    # regeneration. It was, repeatedly: every manifest emitter hardcoded
-    # '0.0.1', so a project that had published 0.0.2 got its manifest reset
-    # and only the 3-way merge (which sdkgen turns off, see
-    # docs/explanation/regeneration-overwrite.md) was hiding it. Declare the
-    # version here and every port reads the same value.
-    #
-    # DECLARE IT IN `model/project.aontu`, the project overlay that
-    # create-sdkgen creates once and never overwrites.
-    #
-    # NOT in `model/sdk.aontu`: create-sdkgen rewrites that file from its
-    # template on every scaffold, and cedar-regen.sh re-scaffolds on every
-    # regen, so a version declared there is erased before the model is built
-    # and the manifest silently keeps the default below. That is not a
-    # hypothetical either — a 33-repo fleet shipped every manifest at 0.0.1
-    # while its git tags climbed past 0.1.1, and no error was ever reported.
-    # Guidance here previously said the project's own model survived a resync;
-    # `project.aontu` is what makes that true (create-sdkgen >= 0.18.1).
-    #
-    # NOT in `model/target/<t>.aontu` either: `target add` overwrites those.
-    #
-    # Per TARGET, not per SDK: ports publish to different registries on
-    # different clocks, and a Python release should not have to move the
-    # npm version.
     version: *'0.0.1' | string
 
-    # Git release tag (all ports).
     tag: {
       active: *true | boolean
-      prefix: *'' | string       # '' -> target name
-      # Who implements the tag publish: 'port' delegates to the port's
-      # own Makefile publish recipe (which may do more, e.g. go proxy
-      # priming); 'root' uses the generated root tag-push recipe (for
-      # ports without a Makefile, e.g. go-cli / go-mcp).
+      prefix: *'' | string
       via: *'port' | string
       vault: {
-        recipe: *'github' | string   # aql `vault exec --for=<recipe>=<alias>`
-        alias: *'github' | string    # default vault alias for the token
+        recipe: *'github' | string
+        alias: *'github' | string
       }
     }
 
-    # Package registry (omit for tag-only ports).
     registry: {
-      # Publication state (tri-state):
-      #   'pending'  — declared + git-tag-published, NOT yet on the
-      #                registry (the default: READMEs point at the git
-      #                tag, deploy publishes the tag only).
-      #   'active'   — package is uploaded to the registry; READMEs show
-      #                the real `npm install`/`pip install`/... command.
-      #   'inactive' — registry deliberately disabled (also tag-only).
-      # Kept as a plain string (default 'pending') rather than a literal
-      # disjunction to sidestep aontu's literal-disjunction fragility;
-      # code (packageMeta.registryState / Deploy) enforces the tri-state.
       state: *'pending' | string
-      # Back-compat alias: `active: true` still means state === 'active'.
-      active: *false | boolean   # real publishes refuse when not active
-      name: *'' | string         # npm | pypi | packagist | rubygems | luarocks
+      active: *false | boolean
+      name: *'' | string
       url: *'' | string
-      package: *'' | string      # registry package name ('' -> derived)
+      package: *'' | string
       vault: {
-        recipe: *'' | string     # aql --for preset (npm, pypi, gem, ...)
-        alias: *'' | string      # vault alias ('' -> registry name)
-        env: *'' | string        # raw env var to inject when no preset exists
+        recipe: *'' | string
+        alias: *'' | string
+        env: *'' | string
       }
     }
   }
@@ -436,100 +145,23 @@ main: kit: feature: &: {
   active: *false | boolean
   title: string
 
-  # Provenance — see the note on `main: kit: target: &:` above.
   base:     *'' | string
   origname: *'' | string
   package:  *'' | string
 
-  # TODO: version '0.0.1' | semver # where semver is a string format type as per semver.org
   version: *'0.0.1' | string
 
-  # APPLICABILITY (docs/design/feature-tags.md). What this feature requires
-  # of a target; it applies where `needs` is a subset of the target's
-  # `provides`. Empty means "applies anywhere", so every feature that
-  # predates the gate is unaffected — the gate is additive by construction.
-  #
-  # A tag, not a target list: a list has to be edited for targets the
-  # feature's author has never heard of, so a published package would
-  # starve every target added after its release.
-  #
-  # The vocabulary is closed and lives in `main: kit: target: &: provides`.
-  #
-  # A MAP keyed by tag, not a list, for the reason `contributor` is a map:
-  # aontu unifies maps by key, so a package can add one tag without
-  # restating the others. A list here also hangs the unifier outright on a
-  # real project's model (a defaulted list disjunction under this spread),
-  # which is what settled the shape.
   needs: &: boolean
 
-  # Transport role (station design §8.4): how the feature relates to the
-  # transport slot. 'base' REPLACES ctx.utility.fetcher outright (only the
-  # `test` feature); 'wrap' wraps it in init() (netsim, retry, cache,
-  # ratelimit, timeout, proxy - and station's own feature); 'none' is
-  # hook-only. Carried into the embedded config by configDefinition so
-  # station can validate the resolved feature order. Declared, never
-  # inferred: the obvious signal, an empty `hook: {}`, is wrong for a
-  # feature that both wraps AND dispatches hooks (station does).
   transport: *'none' | 'base' | 'wrap'
 
-  # SPEC-DERIVED OPTIONS. Facts apidef records from the OpenAPI spec, mapped
-  # onto the key in this feature's `config.options` that should carry them:
-  #
-  #   spec: { authexchange: 'exchange' }
-  #
-  # configDefinition performs the overlay at generation time, so the fact
-  # reaches the SDK's embedded config without a project restating what its
-  # own spec already says. The fact name comes from a CLOSED vocabulary
-  # (`SPEC_FACTS` in ts/src/utility.ts); an unknown name is ignored rather
-  # than failing, so a project on an older sdkgen is unaffected.
-  #
-  # A map keyed by fact name, for the same reason `needs` is a map: aontu
-  # unifies maps by key, so a package can add one entry without restating
-  # the others.
   spec: &: string
 
-  # THE FEATURE'S OWN OPTION SCHEMA.
-  #
-  # `config.options` is the DEFAULTS map: what happens when the caller says
-  # nothing. It is also the README's option table, and — read by example —
-  # the type of each option in the generated option spec.
-  #
-  # `config.optspec` is for what a default cannot say:
-  #   - an option with NO default (a `sink` callback, an injected clock, a
-  #     value the caller either supplies or does not). Undeclared, these
-  #     were invisible to the spec AND missing from the docs table.
-  #   - an option whose default understates its type. netsim's `latency: 0`
-  #     reads as "a number" while the feature also takes `{ min, max }`.
-  #
-  # Values are struct.validate sentinels — '`$FUNCTION`', '`$MAP`', or a
-  # union ['`$ONE`', '`$NUMBER`', '`$MAP`']. A name in both maps takes its
-  # TYPE from here and its default from `config.options`.
-  #
-  # `config.strict: true` closes the feature's spec, so an option neither
-  # map declares is rejected instead of passed through. Off by default: the
-  # shipped features are not fully declared yet, and rejecting a working
-  # client's option on upgrade is worse than missing a typo.
   config: {
     optspec: &: top
     strict: *false | boolean
   }
 
-  # PLUGINS — a feature's optional, separately-trimmed parts.
-  #
-  # A feature whose implementation is a thin layer over a library with
-  # OPTIONAL pieces (secrets over sekreto, whose thirteen provider kinds
-  # each carry their own platform cost) declares them here. Each plugin
-  # owns a template subfolder under the feature's own tree, and the
-  # feature trim removes an inactive one exactly as it removes an
-  # inactive feature — the same walk, one level deeper.
-  #
-  # This is what makes a generated SDK lean: a project whose chain is
-  # `[dotenv, env]` should not carry AWS request signing and seven HTTP
-  # vault clients, and before this it carried all of them because they
-  # were reachable from one import.
-  #
-  # `needs` is the same closed applicability vocabulary a feature uses,
-  # so a plugin requiring something of its target is gated the same way.
   plugin: &: {
     name: key()
     active: *false | boolean
@@ -540,31 +172,16 @@ main: kit: feature: &: {
     # generation rather than at the consumer's first lookup.
     needs: &: boolean
 
-    # The template paths this plugin OWNS, relative to the target
-    # template root, dropped when it is inactive.
-    #
-    # Declared rather than derived from a `plugin/<name>/` directory
-    # convention, because the files a plugin owns are frequently NOT
-    # free to move. sekreto's provider modules are VENDORED: the
-    # vendoring guard holds each file against its upstream path, and
-    # their relative imports (`./support`, `../Sigv4`) only resolve at
-    # upstream's own directory depth. Relocating them under a
-    # convention would break both at once.
-    #
-    # Empty means the convention — `src/feature/<feature>/plugin/<name>/`
-    # — which is right for a plugin whose files sdkgen owns outright.
     path: *[] | [&: string]
 
-    # The plugin DEFINITIONS this plugin's files export, keyed by TARGET,
-    # then by exported symbol, valued by the owning template path (which
-    # must also appear in `path`). This is what lets each Config emit
-    # NAMED imports and hand the feature an explicit `plugins: [...]`
-    # list — upstream sekreto's shape since its registry was replaced by
-    # voxgig/plugin definitions. Target-keyed because the symbol grammar
-    # is the language's own (`awssecrets` in ts, `aws.Secrets` in go),
-    # and one file may export several (ts aws.ts exports awssecrets AND
-    # awsparams), which is why the inner level is a map and not one name.
     def: &: &: string
+
+    stub: &: [&: string]
+
+    deps: &: &: {
+      active: *false | boolean
+      version: *'*' | string
+    }
   }
 
   hook: &: {
@@ -578,7 +195,7 @@ main: kit: feature: &: {
     SetData: {}
     GetData: {}
     GetMatch: {}
-        
+
     PreTarget: {}
     PreSpec: {}
     PreRequest: {}
@@ -587,10 +204,9 @@ main: kit: feature: &: {
     PostOperation: {}
   }
 
-  # Target specific structures 
   target: &: deps: &: {
     active: *false | boolean
-    version: *'*' | string 
+    version: *'*' | string
   }
 }
 
@@ -601,27 +217,6 @@ main: kit: option: &: {
 }
 
 
-# THE SDK CLIENT OPTION SCHEMA — one declaration, every target.
-#
-# A struct.validate SPEC, in struct's own by-example vocabulary: a concrete
-# value is BOTH the type constraint and the default (`base` here means "a
-# string, defaulting to http://localhost:8000"), and a `$SENTINEL` constrains
-# without defaulting. The generated `Spec` module carries it into the SDK,
-# where makeOptions validates the caller's options against it.
-#
-# WHY IT MOVED HERE. It used to be a literal inside every language's
-# make_options template — twenty hand-maintained copies of one schema, two of
-# them (cpp, scala) as JSON string constants. Nothing checked them against
-# each other and nothing checked them against the documented option list, so
-# the runtime contract, the twenty copies and the README were three sources
-# of truth for the same thing. A project that adds an option now adds it in
-# ONE place and every ported target validates it.
-#
-# Keys are the option names a caller passes to the constructor. Unknown
-# top-level keys are DROPPED by validate (not rejected) — that is struct's
-# behaviour, not a choice made here, and it is why `extend` needs an entry:
-# without one the constructor's feature-adoption seam silently received
-# nothing.
 main: kit: optspec: {
 
   # Credentials. '' is the documented "not supplied" value; `auth: null`
@@ -630,7 +225,6 @@ main: kit: optspec: {
   apikey: ''
   secret: ''
 
-  # The API base URL. A `{name}` placeholder is resolved from `server`.
   base: 'http://localhost:8000'
   prefix: ''
   suffix: ''
@@ -639,23 +233,14 @@ main: kit: optspec: {
     prefix: ''
     basic: false
 
-    # WHERE the credential goes and UNDER WHAT NAME. apidef resolves both
-    # from the spec's securityScheme into main.kit.info.security; these are
-    # the per-SDK override, and they are what the generated prepareAuth is
-    # built from. '' means "take what the spec said", so an SDK that does
-    # not set them behaves exactly as it did before.
-    #   in:   header | query | cookie
-    #   name: the header, query parameter or cookie name
     in: ''
     name: ''
   }
 
-  # Extra headers sent with every request: any name, string values.
   headers: {
     '`$CHILD`': '`$STRING`'
   }
 
-  # The operation and method allow-lists, as comma-separated strings.
   allow: {
     method: 'GET,PUT,POST,PATCH,DELETE,OPTIONS'
     op: 'create,update,load,list,remove,command,direct,graphql'
@@ -671,12 +256,8 @@ main: kit: optspec: {
     }
   }
 
-  # Feature INSTANCES supplied at construction (the station adopt path):
-  # class instances, not data, so `$ANY` passes them through verbatim.
   extend: '`$ANY`'
 
-  # Platform seams. A function value does not survive validate (struct drops
-  # it), so `system.fetch` is captured and restored around the call.
   utility: {}
   system: {
     fetch: '`$ANY`'
@@ -693,20 +274,8 @@ main: kit: optspec: {
     keys: 'key,token,id'
   }
 
-  # Server-variable values for a templated base URL (OpenAPI server
-  # variables). Spec defaults arrive through the generated Config; these are
-  # the caller's overrides.
   server: {
     '`$CHILD`': ''
   }
 
-  # `feature` is NOT declared here. It is assembled per target from each
-  # active feature's own `config.options`, which is already the feature's
-  # by-example schema — see helpers/optspec.
 }
-
-
-
-
-
-# Documentation editions extend main.kit.doc through @voxgig/docgen/model/docgen.aon.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/sdkgen",
-  "version": "4.20.0",
+  "version": "4.22.0",
   "main": "dist/sdkgen.js",
   "type": "commonjs",
   "engines": {
@@ -43,7 +43,7 @@
     "voxgig-sdkgen": "bin/voxgig-sdkgen"
   },
   "scripts": {
-    "test": "node --enable-source-maps --test dist-test/**/*.test.js",
+    "test": "node ../tools/comment-gate.cjs && node --enable-source-maps --test dist-test/**/*.test.js",
     "test-some": "node --enable-source-maps --test-name-pattern=\"$npm_config_pattern\" --test dist-test/**/*.test.js",
     "golden": "npm run build && SDKGEN_GOLDEN_UPDATE=1 node --test dist-test/characterize.test.js",
     "watch": "tsc --build src test -w",
@@ -89,10 +89,10 @@
   "peerDependencies": {
     "@tabnas/jsonic": ">=0.6.0",
     "@tabnas/parser": ">=0.8.0",
-    "@voxgig/apidef": ">=8.2.2",
+    "@voxgig/apidef": ">=8.12.0",
     "@voxgig/struct": ">=0.2",
     "@voxgig/util": ">=0.5",
-    "aontu": ">=0.52",
+    "aontu": ">=0.68",
     "jostraca": ">=0.38.1",
     "shape": ">=11.4.1"
   }