@voxgig/sdkgen 3.0.0 → 3.2.0

package/model/sdkgen.aontu

@@ -32,6 +32,25 @@ main: kit: test: {
     # Overridable per target:
     #   main: kit: target: go: test: live: strict: true
     strict: *false | 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
+    # `app/`. NOTHING in an API definition says so — it is a property of the
+    # sibling project — so it cannot be inferred, and inferring it put an
+    # unconditional `git clone && cd app && npm install && npm run build` into
+    # a generated provider's CI, which fails the job for any repo without one.
+    app: *false | boolean
   }
 }
 
@@ -81,6 +100,37 @@ main: kit: repo: {
 }
 
 
+# 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
+}
+
+main: kit: contributor: &: {
+  name: string
+  url: *'' | string
+}
+
+
 main: kit: target: &: {
   name: key()
   active: *true | boolean
@@ -109,6 +159,16 @@ main: kit: target: &: {
     # floors imposed by their dependencies.
     goversion: *'' | string
   }
+  # WHO WROTE THIS PACKAGE, when it differs from the model-wide
+  # `main: kit: author`. One model can produce packages with different
+  # authors: an SDK is a generated artefact of the publisher, while a Seneca
+  # provider is independently released and has its own maintainers. Unset
+  # inherits the model-wide value, which itself defaults to the publisher.
+  author: {
+    name: *'' | string
+    url: *'' | string
+  }
+
   deps: &: {
     active: *false | boolean
     version: *'*' | string
@@ -147,6 +207,76 @@ main: kit: target: &: {
   # 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
+
+    # 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>`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/sdkgen",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "main": "dist/sdkgen.js",
   "type": "commonjs",
   "engines": {

package/project/.sdk/model/target/go-cli.aontu

@@ -43,7 +43,6 @@ main: kit: feature: &: target: 'go-cli': deps: &: {
 
 # Publication: tag-only — the Go module proxy resolves versions from the
 # go-cli/vX.Y.Z GitHub tag; there is no package registry to upload to.
-# Publication.
 #
 # `target add <t>` OVERWRITES this file, so a project must never set its
 # publication values here — voxgig-solardemo-sdk lost its pinned npm package

package/project/.sdk/model/target/go-mcp.aontu

@@ -37,7 +37,6 @@ main: kit: feature: &: target: 'go-mcp': deps: &: {
 
 # Publication: tag-only — the Go module proxy resolves versions from the
 # go-mcp/vX.Y.Z GitHub tag; there is no package registry to upload to.
-# Publication.
 #
 # `target add <t>` OVERWRITES this file, so a project must never set its
 # publication values here — voxgig-solardemo-sdk lost its pinned npm package

package/project/.sdk/model/target/java.aontu

@@ -25,7 +25,6 @@ main: kit: feature: &: target: java: deps: &: {
 
 # Publication: tag-only for now (tag java/vX.Y.Z) — Maven Central
 # publication via the Sonatype Central Portal is declared but pending.
-# Publication.
 #
 # `target add <t>` OVERWRITES this file, so a project must never set its
 # publication values here — voxgig-solardemo-sdk lost its pinned npm package

package/project/.sdk/model/target/kotlin.aontu

@@ -25,7 +25,6 @@ main: kit: feature: &: target: kotlin: deps: &: {
 
 # Publication: tag-only for now (tag kotlin/vX.Y.Z) — Maven Central
 # publication via the Sonatype Central Portal is declared but pending.
-# Publication.
 #
 # `target add <t>` OVERWRITES this file, so a project must never set its
 # publication values here — voxgig-solardemo-sdk lost its pinned npm package

package/project/.sdk/model/target/lean.aontu

@@ -39,7 +39,6 @@ main: kit: feature: &: target: lean: deps: &: {
 
 # Publication: Reservoir (Lean package index) — declared, publish pending
 # (git-tag only for now).
-# Publication.
 #
 # `target add <t>` OVERWRITES this file, so a project must never set its
 # publication values here — voxgig-solardemo-sdk lost its pinned npm package

package/project/.sdk/model/target/py-data.aontu

@@ -52,7 +52,6 @@ main: kit: feature: &: target: 'py-data': deps: &: {
 
 # Publication: pypi registry (declared, publish pending — git-tag only),
 # same posture as the `py` target.
-# Publication.
 #
 # `target add <t>` OVERWRITES this file, so a project must never set its
 # publication values here — voxgig-solardemo-sdk lost its pinned npm package

package/project/.sdk/model/target/scala.aontu

@@ -25,7 +25,6 @@ main: kit: feature: &: target: scala: deps: &: {
 
 # Publication: tag-only for now (tag scala/vX.Y.Z) — Maven Central
 # publication via the Sonatype Central Portal is declared but pending.
-# Publication.
 #
 # `target add <t>` OVERWRITES this file, so a project must never set its
 # publication values here — voxgig-solardemo-sdk lost its pinned npm package

package/project/.sdk/model/target/seneca-provider.aontu

@@ -0,0 +1,118 @@
+# Seneca provider target — a Seneca plugin that exposes this API's entities
+# as Seneca entities (`provider/<name>/<entity>`), layered on the sibling
+# `ts` SDK. It is not a language SDK in its own right, so every standard
+# generation phase is switched off below and Main_seneca-provider emits the
+# whole package, exactly as go-cli / go-mcp / py-data do.
+#
+# Requires the `ts` target in the same SDK project (Main throws when it is
+# absent): the plugin imports the published TypeScript SDK.
+#
+# UNLIKE the other consumer targets, this one generates into ITS OWN REPO.
+# A Seneca provider is an independently released npm package under the
+# @seneca scope, with its own LICENSE, CI workflow and release cadence, and
+# it depends on the SDK as an ordinary published dependency rather than by
+# path. Point it at that repo from the PROJECT model:
+#
+#   main: kit: target: 'seneca-provider': output: path: '../../seneca/seneca-acme-provider'
+#
+# Relative to the SDK repo root. Left unset here on purpose — every project's
+# provider repo is somewhere different, and a concrete value here would
+# CONFLICT with the project's rather than yield to it (see the publication
+# note below). Unset means the ordinary in-tree `<sdk-repo>/seneca-provider/`,
+# which is a usable default for a first look at the output.
+
+main: kit: target: 'seneca-provider': {
+
+  title: 'Seneca Provider'
+  ext: ts
+  comment: line: "//"
+  module: name: '$$name$$'
+  srcfeature: false
+
+  # Per-generation-phase activation. Mirrors py-data: every standard phase is
+  # off and Main emits the package. README, docs and tests ARE generated — by
+  # Main, not by the standard cmps, which assume an SDK-shaped package and
+  # would emit wrong content here.
+  phase: {
+    entity:     { active: false }
+    feature:    { active: false }
+    readme:     { active: false }
+    agentguide: { active: false }
+    test:       { active: false }
+  }
+
+  # `kind` is a COMMA-SEPARATED LIST of manifest sections, not a single one.
+  # collectDeps deduplicates by package name and this map is keyed by name, so
+  # a package belonging in two sections cannot be declared twice — it says so
+  # here instead. See `seneca` below for the case that forced it.
+  deps: &: {
+    kind: *'prod' | string
+  }
+
+  # The Seneca plugin contract. `@seneca/provider` supplies entityBuilder and
+  # the keymap message this plugin's `prepare` posts; the rest are the host
+  # framework a plugin runs inside and so are PEER deps — a plugin that
+  # bundled its own seneca would run against a different instance than the
+  # application it is loaded into.
+  #
+  # The ts SDK dependency is emitted by Main from the model's published
+  # package name, so it is not declared here.
+  deps: {
+    '@seneca/maintain':  { active: true, version: '^0.1.0', kind: prod }
+
+    '@seneca/env':       { active: true, version: '>=0.4',  kind: peer }
+    '@seneca/provider':  { active: true, version: '>=4',    kind: peer }
+
+    # PEER *and* DEV. Peer for the reason above — the plugin must attach to
+    # the host application's seneca instance. Dev because the generated test
+    # suite does `require('seneca')` itself, so a clean `npm install && npm
+    # test` in a fresh checkout has to produce one. Relying on npm's automatic
+    # peer installation instead is what dropping this from the manifest
+    # amounted to, and that is npm-version- and client-specific: pnpm and
+    # `--legacy-peer-deps` both leave the suite with no seneca to require.
+    'seneca':            { active: true, version: '>=3||>=4.0.0-rc2', kind: 'peer,dev' }
+
+    'seneca-entity':     { active: true, version: '>=26',   kind: peer }
+    'seneca-promisify':  { active: true, version: '>=3',    kind: peer }
+
+    '@seneca/doc':       { active: true, version: '^8.0.0', kind: dev }
+    '@types/node':       { active: true, version: '^24.0.0', kind: dev }
+    'seneca-msg-test':   { active: true, version: '^4.1.0', kind: dev }
+    'typescript':        { active: true, version: '^5.4.5', kind: dev }
+  }
+}
+
+
+# Feature-deps map slot — every target carries this so the same feature can
+# specify per-target dep variants.
+main: kit: feature: &: target: 'seneca-provider': deps: &: {
+  kind: *'prod' | string
+}
+
+
+# Publication: npm registry, under the @seneca scope rather than the SDK's
+# own. The package name is NOT derived from the SDK slug the way a language
+# target's is — a provider is `@seneca/<name>-provider` — so Main sets it
+# from the model and a project can pin it like any other.
+#
+# `target add <t>` OVERWRITES this file, so a project must never set its
+# publication values here — voxgig-solardemo-sdk lost its pinned npm package
+# name exactly that way. Set them in the project's own model
+# (`model/sdk.aontu`), where they survive a resync.
+#
+# For that to work this file must LEAVE THOSE KEYS UNSET: in aontu a concrete
+# value does not yield to another concrete value, it CONFLICTS, and two
+# defaults conflict too. The schema (@voxgig/sdkgen/model/sdkgen.aontu)
+# already defaults `tag.active`, `registry.state`, `registry.active` and
+# `registry.package`, so a project's concrete value wins over the default and
+# repeating them here would only take that away.
+#
+# What remains below is per-target registry IDENTITY, which is not a project
+# choice and stays concrete.
+main: kit: target: 'seneca-provider': publish: {
+  registry: {
+    name: 'npm'
+    url: 'https://registry.npmjs.org'
+    vault: { recipe: 'npm', alias: 'npm' }
+  }
+}

package/project/.sdk/model/target/zig.aontu

@@ -25,7 +25,6 @@ main: kit: feature: &: target: zig: deps: &: {
 # routes deploy-zig to the root tag-push recipe. WITHOUT it, Deploy.ts falls
 # through to `make -C zig publish` — but zig's Makefile has no `publish` target,
 # so the deploy fails. Mirror c.aontu exactly.
-# Publication.
 #
 # `target add <t>` OVERWRITES this file, so a project must never set its
 # publication values here — voxgig-solardemo-sdk lost its pinned npm package

package/project/.sdk/src/cmp/js/Package_js.ts

@@ -12,6 +12,7 @@ import {
   PUBLISHER,
   PUBLISHER_URL,
   packageVersion,
+  authorInfo,
 } from '@voxgig/sdkgen'
 
 
@@ -29,6 +30,12 @@ const Package = cmp(async function Package(props: any) {
 
   const model: Model = ctx$.model
 
+  // WHO WROTE THIS PACKAGE. Per target, falling back to the model-wide value
+  // and then to the publisher — so a manifest cannot go on naming Voxgig
+  // while the model names someone else, which is exactly what the hardcoded
+  // constant here did.
+  const author = authorInfo(model, target.name)
+
   const feature = getModelPath(model, `main.${KIT}.feature`)
 
   const only = (kind: string, deps: any) =>
@@ -79,7 +86,7 @@ const Package = cmp(async function Package(props: any) {
       "clean": "rm -rf node_modules yarn.lock package-lock.json",
       "reset": "npm run clean && npm i && npm test",
     },
-    author: { name: PUBLISHER, url: PUBLISHER_URL },
+    author,
 
     // TODO: needs to be config
     license: 'MIT',

package/project/.sdk/src/cmp/ocaml/Package_ocaml.ts

@@ -4,6 +4,7 @@ import {
   File,
   cmp,
   packageVersion,
+  authorInfo,
 } from '@voxgig/sdkgen'
 
 
@@ -19,6 +20,12 @@ const Package = cmp(async function Package(props: any) {
   const target = props.target
   const model = ctx$.model
 
+  // WHO WROTE THIS PACKAGE. Per target, falling back to the model-wide value
+  // and then to the publisher — so a manifest cannot go on naming Voxgig
+  // while the model names someone else, which is exactly what the hardcoded
+  // constant here did.
+  const author = authorInfo(model, target.name)
+
   const pkg = packageName(model)
 
   File({ name: pkg + '.opam' }, () => {
@@ -26,8 +33,8 @@ const Package = cmp(async function Package(props: any) {
 name: "${pkg}"
 version: "${packageVersion(model, target.name)}"
 synopsis: "${model.const.Name} SDK for OCaml (generated by @voxgig/sdkgen)"
-maintainer: "voxgig"
-authors: "voxgig"
+maintainer: "${author.name}"
+authors: "${author.name}"
 license: "MIT"
 homepage: "https://voxgig.com"
 bug-reports: "https://voxgig.com"

package/project/.sdk/src/cmp/php/Package_php.ts

@@ -6,7 +6,8 @@ import {
   collectDeps,
   pkgDescription,
   keywords,
-  repoInfo, packageName
+  repoInfo, packageName,
+  authorInfo,
 } from '@voxgig/sdkgen'
 
 
@@ -21,6 +22,12 @@ const Package = cmp(async function Package(props: any) {
 
   const model: Model = ctx$.model
 
+  // WHO WROTE THIS PACKAGE. Per target, falling back to the model-wide value
+  // and then to the publisher — so a manifest cannot go on naming Voxgig
+  // while the model names someone else, which is exactly what the hardcoded
+  // constant here did.
+  const author = authorInfo(model, target.name)
+
   // Package namespace mirrors the npm scope (model.origin, e.g. "voxgig-sdk").
   // If origin already ends in "-sdk" the slug stands alone; otherwise append
   // "-sdk" (matches the TS Package generator).
@@ -39,7 +46,7 @@ const Package = cmp(async function Package(props: any) {
   "homepage": "${repoUrl}",
   "license": "MIT",
   "authors": [
-    { "name": "Voxgig", "homepage": "https://voxgig.com" }
+    { "name": "${author.name}"${'' === author.url ? '' : `, "homepage": "${author.url}"`} }
   ],
   "support": {
     "issues": "${issuesUrl}",

package/project/.sdk/src/cmp/rb/Package_rb.ts

@@ -6,7 +6,8 @@ import {
   collectDeps,
   pkgDescription,
   repoInfo, packageName,
-  packageVersion
+  packageVersion,
+  authorInfo,
 } from '@voxgig/sdkgen'
 
 
@@ -21,6 +22,12 @@ const Package = cmp(async function Package(props: any) {
 
   const model: Model = ctx$.model
 
+  // WHO WROTE THIS PACKAGE. Per target, falling back to the model-wide value
+  // and then to the publisher — so a manifest cannot go on naming Voxgig
+  // while the model names someone else, which is exactly what the hardcoded
+  // constant here did.
+  const author = authorInfo(model, target.name)
+
   // Gem name is namespaced to model.origin (e.g. "voxgig-sdk"). RubyGems
   // names can't contain "/", so the parts are hyphen-joined. The require
   // path (`${model.name}_sdk`) is unchanged.
@@ -58,7 +65,7 @@ gemspec
     Content(`Gem::Specification.new do |spec|
   spec.name          = "${gemName}"
   spec.version       = "${packageVersion(model, target.name)}"
-  spec.authors       = ["Voxgig"]
+  spec.authors       = ["${author.name}"]
   spec.summary       = "${pkgDescription(model, 'rb')}"
   spec.description   = "${pkgDescription(model, 'rb')}"
   spec.license       = "MIT"