@voxgig/sdkgen-infrapack 0.0.10 → 0.0.11

package/.sdk/src/cmp/seneca-provider/Extras_seneca-provider.ts

@@ -18,6 +18,58 @@ import {
 // generated provider is verified without a server.
 
 
+// WHERE A FETCHED SDK CHECKOUT LIVES, inside this repo.
+//
+// Fixed, and the same under every layout, which is the whole point: it is
+// what lets the generated docs, the live-test instructions and `make regen`
+// name the SDK source without naming anyone's directory layout. Gitignored —
+// the checkout is derived from the pin and disposable, so committing it would
+// vendor the SDK into a repo that already depends on it.
+//
+// NOT a git submodule. A submodule pins a COMMIT and puts the pin in git's
+// own plumbing, where updating it is a second repository operation and a
+// stale one is invisible in a normal diff. The pin here is an ordinary
+// committed file naming a TAG, regenerated from the model like everything
+// else, so it moves with the SDK version it belongs to and shows up in review.
+const SDK_SRC_DIR = '.sdksrc'
+
+
+// The SDK this provider was generated from: repository, release tag, and the
+// published package the tag corresponds to.
+//
+// Committed, and REGENERATED — so it cannot drift from the dependency in
+// package.json, which comes from the same model version. The tag is
+// `v<version>` because that is what the SDK's publish workflow cuts for its
+// primary npm target.
+//
+// This is the file that makes the repo independently buildable: with it, the
+// SDK that generates this provider can be fetched from scratch, at the exact
+// revision that generated it, by a script that knows nothing else.
+const SdkPin = cmp(function SdkPin(props: any) {
+  const { provider } = props
+
+  // Nothing to pin without a repository to fetch from. Emitting a pin with an
+  // empty `repo` would be a file that looks like a promise and cannot be
+  // kept.
+  if (!provider.sdkPinned) {
+    return
+  }
+
+  File({ name: 'sdk-pin.json' }, () => {
+    Content(JSON.stringify({
+      note: 'GENERATED. The SDK this provider is generated from. ' +
+        '`make sdk-src` fetches it; `make regen` regenerates this repo ' +
+        'from it. Edit the SDK project model, not this file.',
+      repo: provider.sdkRepoUrl,
+      tag: provider.sdkTag,
+      dir: provider.sdkSrc,
+      package: provider.sdkPkg,
+      version: provider.sdkVersion,
+    }, null, 2) + '\n')
+  })
+})
+
+
 // Does this entity's load op have a real identifying param (path or
 // required query), e.g. GET /result?trace_id=? A paramless GET has none.
 function loadHasKey(e: any): boolean {
@@ -710,7 +762,7 @@ const BasicMessages = require('../dist-test/basic.messages')
 ${'' === provider.liveBase ? '' : `
 // The live tests run against the companion test server in the SDK repo
 // (\`app/\`), which serves this by default. Start it with:
-//   cd ${provider.sdkrel}/app && npm start
+//   cd ${provider.sdkSrc}/app && npm start
 const LIVE_BASE = process.env.${provider.ENV}_TEST_BASE || '${provider.liveBase}'
 `}
 
@@ -1427,7 +1479,7 @@ async function makeSeneca() {
       Content(`/* Manual script: read from a running ${provider.api} server.
  *
  * Start the companion test server from the SDK repo first:
- *   cd ${provider.sdkrel}/app && npm start
+ *   cd ${provider.sdkSrc}/app && npm start
  *
  * Then:  node test/live.js
  */
@@ -1501,7 +1553,7 @@ async function run() {
         Content(`/* Manual script: exercise the full CRUD cycle against a running server.
  *
  * Start the companion test server from the SDK repo first:
- *   cd ${provider.sdkrel}/app && npm start
+ *   cd ${provider.sdkSrc}/app && npm start
  *
  * Then:  node test/quick.js
  *
@@ -2220,7 +2272,7 @@ The companion test server is distributed in the SDK's source repository
 only. From a checkout beside this one:
 
 \`\`\`sh
-cd ${provider.sdkrel}/app && npm start
+cd ${provider.sdkSrc}/app && npm start
 \`\`\`
 
 Then \`node test/live.js\` reads from it, and \`node test/quick.js\` runs a
@@ -2476,30 +2528,27 @@ back as a puzzling 404.
 
 `
 
-  // The clone lands in a directory named for the repository, so the cd that
-  // follows can be exact rather than "wherever you put it". With no repo url
-  // to clone from, the only path anyone can be told is the relative one back
-  // to the SDK project.
-  const sdkRepo = String(provider.sdkRepoUrl || '')
-  const sdkDir = sdkRepo.replace(/\/+$/, '').split('/').pop() || 'sdk'
-  const appDir = '' === sdkRepo ? `${provider.sdkrel}/app` : `${sdkDir}/app`
+  // ONE PATH, BOTH WAYS IN. `provider.sdkSrc` is where the SDK source is
+  // reached: the pinned fetch target when the SDK has a repository, and the
+  // relative walk back when it has none and nothing can be fetched. So the
+  // instruction differs but the path does not, and neither spelling carries a
+  // directory name off anyone's machine.
+  const appDir = `${provider.sdkSrc}/app`
 
-  const getServer = '' === sdkRepo ?
+  const getServer = provider.sdkPinned ?
     `You also need a server to talk to. The SDK itself installs from npm,
 but its test server does not — it ships only in the SDK's source
-project, in its \`app\` folder, which is at \`${provider.sdkrel}\`
-relative to this one.
-` :
-    `You also need a server to talk to. The SDK itself installs from npm,
-but its test server does not — it ships only in the SDK's source
-repository, so clone that:
+repository. \`make sdk-src\` fetches that source at the tag this plugin
+was generated from, into \`${provider.sdkSrc}\`:
 
 \`\`\`sh
-$ git clone ${sdkRepo}.git
+$ make sdk-src
 \`\`\`
-
-If you already have that checkout beside this plugin, it is at
-\`${provider.sdkrel}\`, and you can skip the clone.
+` :
+    `You also need a server to talk to. The SDK itself installs from npm,
+but its test server does not — it ships only in the SDK's source
+project, in its \`app\` folder, which is at \`${provider.sdkSrc}\`
+relative to this one.
 `
 
   // What a bare GET on the probe route answers with, when the model has one.
@@ -2921,11 +2970,11 @@ calls. Your seeded ids will not exist there, so read the ids you need
 from a \`list$\` first.
 
 `)
-      if (hasServer && '' !== sdkRepo) {
+      if (hasServer && provider.sdkPinned) {
         Content(`A test server that answers on that address is distributed in the SDK's
-source repository, which is the only place it ships. Clone
-\`${sdkRepo}\`, then run \`npm install\`, \`npm run build\` and
-\`npm start\` in its \`app\` folder.
+source repository, which is the only place it ships. \`make sdk-src\`
+fetches that source at the pinned tag; then run \`npm install\`,
+\`npm run build\` and \`npm start\` in its \`app\` folder.
 
 `)
       }
@@ -3495,20 +3544,27 @@ $ npm install
 \`\`\`
 
 If you are changing the SDK and this plugin together, point npm at a
-local checkout instead. Clone the SDK beside this repository, at the path
-this project expects, and build it — it does not commit its build output:
+local checkout instead. \`make sdk-src\` fetches the SDK this repository is
+generated from — the repository and tag in \`sdk-pin.json\` — into
+\`${provider.sdkSrc}\`, then build it, because it does not commit its build
+output:
 
 \`\`\`sh
-$ git clone ${provider.sdkRepoUrl}.git \\
-    ${provider.sdkrel}
-$ cd ${provider.sdkrel}/ts
+$ make sdk-src
+$ cd ${provider.sdkSrc}/ts
 $ npm install && npm run build
 \`\`\`
 
+Already have that checkout elsewhere? Point the same target at it:
+
+\`\`\`sh
+$ make sdk-src SDK_SRC_FROM=../path/to/your/checkout
+\`\`\`
+
 Then link it in, without committing the change to \`package.json\`:
 
 \`\`\`sh
-$ npm install --no-save ${provider.sdkrel}/ts
+$ npm install --no-save ${provider.sdkSrc}/ts
 \`\`\`
 
 npm creates a symlink, so a rebuild of the SDK is picked up here with no
@@ -3562,10 +3618,12 @@ $ TEST_PATTERN=${pattern} npm run test-some
 
   if ('' !== liveBase) {
     sec('Run the live tests against a server', `The companion test server ships only in the SDK's source repository, not
-in the published package. From the checkout beside this one:
+in the published package. \`make sdk-src\` fetches that source at the pinned
+tag; the server is in its \`app\` folder:
 
 \`\`\`sh
-$ cd ${provider.sdkrel}/app
+$ make sdk-src
+$ cd ${provider.sdkSrc}/app
 $ npm install && npm run build && npm start
 \`\`\`
 
@@ -4795,9 +4853,10 @@ edit: the edit will not survive. The next generation run overwrites this
 repository, without a merge and without a warning. A fix applied here is a fix
 that has to be applied again, silently, forever.
 
-The source of truth is the SDK project's model — \`${provider.sdkrel}\` from
-here, if both are checked out — together with the sdkgen component that emits
-this target. A change to *what* the API offers belongs in the model; a change to
+The source of truth is the SDK project's model — the repository and tag named
+in \`sdk-pin.json\`, which \`make sdk-src\` fetches to \`${provider.sdkSrc}\` —
+together with the sdkgen component that emits this target. A change to *what*
+the API offers belongs in the model; a change to
 *how* the provider expresses it belongs in the component. Both are versioned,
 both regenerate every provider built this way rather than just this one, and
 both are where a fix is worth making. See
@@ -4952,4 +5011,6 @@ export {
   Docs,
   seedRecord,
   parentSeed,
+  SdkPin,
+  SDK_SRC_DIR,
 }

package/.sdk/src/cmp/seneca-provider/Gitignore_seneca-provider.ts

@@ -20,6 +20,8 @@
 // The content below is the template's, byte for byte. It carried no
 // placeholder, so nothing about `stdrep` substitution changes by moving it.
 
+import { SDK_SRC_DIR } from './Extras_seneca-provider'
+
 import {
   Content,
   File,
@@ -151,6 +153,13 @@ test/local-env.js
 # every regeneration leaves the provider repo dirty with hundreds of
 # untracked files.
 .jostraca/
+
+# The SDK source, fetched by \`make sdk-src\` at the repository and tag in
+# sdk-pin.json. DERIVED and disposable: the pin is the committed fact, and
+# the checkout can be refetched from it at any time. Committing it would
+# vendor the whole SDK into a repo that already depends on its published
+# package.
+${SDK_SRC_DIR}/
 `)
   })
 })

package/.sdk/src/cmp/seneca-provider/Main_seneca-provider.ts

@@ -15,7 +15,9 @@ import {
   KIT,
 } from '@voxgig/apidef'
 
-import { Tests, Scripts, Workflow, Readme, Docs } from './Extras_seneca-provider'
+import {
+  Tests, Scripts, Workflow, Readme, Docs, SdkPin, SDK_SRC_DIR,
+} from './Extras_seneca-provider'
 import { Gitignore } from './Gitignore_seneca-provider'
 
 
@@ -675,6 +677,37 @@ const Main = cmp(function Main(props: any) {
   // once by the external pass — see cmp/ExternalTarget.
   const sdkrel = ctx$.sdkrelpath || '..'
 
+  // WHERE THE SDK SOURCE IS, AND WHY IT IS NOT `sdkrel`.
+  //
+  // `sdkrel` is a walk back through the FILESYSTEM, and it is committed here
+  // — into the docs, the live-test headers and the develop-locally recipe.
+  // That makes generated content depend on one machine's directory layout.
+  // voxgig-solardemo-sdk committed '../../voxgig-sdk/voxgig-solardemo-sdk',
+  // where `voxgig-sdk` is the name of a workspace directory on one laptop and
+  // no part of any model; a second developer with both repos under a
+  // differently named parent regenerates a diff in tracked files and follows
+  // instructions that are wrong on one of the two machines.
+  //
+  // So the SDK is named by its PIN instead — repository and release tag, both
+  // facts about the SDK rather than about anyone's disk — and fetched to a
+  // fixed path INSIDE this repo. `make sdk-src` puts it there. The path is
+  // then the same string on every machine and under every layout, which is
+  // what lets this repo regenerate itself from a checkout it fetched (see
+  // SdkPin and the Makefile).
+  //
+  // The tag is `v<version>`: the SDK's publish workflow cuts exactly that for
+  // its primary npm target, so the pin needs no separate bookkeeping and
+  // cannot drift from the dependency version.
+  const sdkRepoUrl = String(repoInfo(model).repoUrl || '')
+  const sdkTag = 'v' + sdkVersion
+  const sdkRepoDir = sdkRepoUrl.replace(/[/]+$/, '').split('/').pop() || 'sdk'
+
+  // With NO repo url there is nothing to pin and nothing to clone, so the
+  // only path anyone can be told is still the relative one. Honest, and the
+  // case the pin cannot improve.
+  const sdkPinned = '' !== sdkRepoUrl
+  const sdkSrc = sdkPinned ? SDK_SRC_DIR + '/' + sdkRepoDir : sdkrel
+
   // Where a live run points — and whether there is anything honest to point
   // it at.
   //
@@ -746,10 +779,15 @@ const Main = cmp(function Main(props: any) {
     repoUrl: repo.url,
     // The SDK's own repo, for pointing at the companion test server which is
     // only distributed in source.
-    sdkRepoUrl: repoInfo(model).repoUrl,
+    sdkRepoUrl,
+    sdkTag,
+    sdkRepoDir,
+    sdkPinned,
+    // Where the SDK SOURCE is reached, as every generated file spells it.
+    // Layout-independent when the SDK has a repo to pin. See above.
+    sdkSrc,
     api: apiName(model),
     version: packageVersion(model, target.name),
-    sdkrel,
     liveBase,
     liveApp,
     // The sponsor line. @seneca/maintain's `content_readme` check requires
@@ -793,6 +831,7 @@ const Main = cmp(function Main(props: any) {
     replace: { ...ctx$.stdrep },
   })
 
+  SdkPin({ provider })
   PackageJson({ provider, target })
   ProviderSource({ provider })
   ProviderDoc({ provider })

package/.sdk/tm/seneca-provider/Makefile

@@ -1,4 +1,6 @@
-.PHONY: all build test clean reset
+# GENERATED by @voxgig/sdkgen. Do not edit.
+
+.PHONY: all build test clean reset sdk-src sdk-clean regen
 
 all: build test
 
@@ -13,3 +15,111 @@ clean:
 
 reset:
 	npm run reset
+
+
+# ---------------------------------------------------------------------------
+# THIS REPOSITORY IS GENERATED, AND CAN REGENERATE ITSELF.
+#
+# Everything below fetches the SDK named in sdk-pin.json and runs the
+# generator from it. Nothing here needs a sibling checkout or a particular
+# directory layout: the pin names a repository and a TAG, and the checkout
+# lands inside this repo at a fixed path.
+#
+# NOT a git submodule, deliberately. A submodule pins a commit in git's own
+# plumbing, where a stale one is invisible in a normal diff and updating it is
+# a second repository operation. sdk-pin.json is an ordinary committed file,
+# regenerated from the model with everything else, so it moves with the SDK
+# version it belongs to and shows up in review.
+# ---------------------------------------------------------------------------
+
+SDK_PIN := sdk-pin.json
+SDK_REPO := $(shell node -p "require('./$(SDK_PIN)').repo" 2>/dev/null)
+SDK_TAG := $(shell node -p "require('./$(SDK_PIN)').tag" 2>/dev/null)
+SDK_DIR := $(shell node -p "require('./$(SDK_PIN)').dir" 2>/dev/null)
+
+# Point at a checkout you already have instead of fetching one:
+#   make sdk-src SDK_SRC_FROM=../path/to/sdk
+SDK_SRC_FROM ?=
+
+# Fetch (or update) the SDK source at the pinned tag.
+#
+# A TAG, not a branch: the point is the exact revision this repository was
+# generated from, so that regenerating reproduces what is committed here
+# rather than whatever main happens to say today.
+sdk-src:
+	@set -e; \
+	test -n "$(SDK_REPO)" || { echo "sdk-src: no repo in $(SDK_PIN)"; exit 1; }; \
+	test -n "$(SDK_TAG)" || { echo "sdk-src: no tag in $(SDK_PIN)"; exit 1; }; \
+	if [ -n "$(SDK_SRC_FROM)" ]; then \
+	  echo "sdk-src: using $(SDK_SRC_FROM) (not fetching)"; \
+	  rm -rf "$(SDK_DIR)"; mkdir -p "$$(dirname "$(SDK_DIR)")"; \
+	  ln -s "$$(cd "$(SDK_SRC_FROM)" && pwd)" "$(SDK_DIR)"; \
+	  exit 0; \
+	fi; \
+	if [ -d "$(SDK_DIR)/.git" ]; then \
+	  echo "sdk-src: fetching $(SDK_TAG) in $(SDK_DIR)"; \
+	  git -C "$(SDK_DIR)" fetch --depth 1 origin "refs/tags/$(SDK_TAG):refs/tags/$(SDK_TAG)" 2>/dev/null || \
+	    git -C "$(SDK_DIR)" fetch origin "refs/tags/$(SDK_TAG):refs/tags/$(SDK_TAG)"; \
+	  git -C "$(SDK_DIR)" checkout -q "refs/tags/$(SDK_TAG)"; \
+	else \
+	  echo "sdk-src: cloning $(SDK_REPO) at $(SDK_TAG) into $(SDK_DIR)"; \
+	  rm -rf "$(SDK_DIR)"; mkdir -p "$$(dirname "$(SDK_DIR)")"; \
+	  git clone --depth 1 --branch "$(SDK_TAG)" "$(SDK_REPO).git" "$(SDK_DIR)"; \
+	fi; \
+	echo "sdk-src: $(SDK_DIR) is at $(SDK_TAG)"
+
+sdk-clean:
+	rm -rf "$(SDK_DIR)"
+
+# Regenerate this repository from the pinned SDK.
+#
+# The SDK's model says where its provider goes, and that value is a fact about
+# ONE developer's checkout layout — it cannot describe being cloned in here.
+# So the destination is given to the generator AT RUN TIME instead:
+#
+#   path       ../..  — from the SDK checkout up to this repository root
+#   enclosing  the output folder CONTAINS the SDK project, which the
+#              generator refuses unless asked, because one `..` too many
+#              writes a package over an unrelated repo
+#
+# See @voxgig/sdkgen docs/explanation/out-of-tree-targets.md.
+# The generate-time output override arrived in @voxgig/sdkgen 4.16.0, and
+# older versions IGNORE it SILENTLY: generation falls back to the destination
+# in the SDK's own model, which from in here resolves to a folder that does
+# not exist, gets skipped, and reports success having written nothing. That is
+# not hypothetical — it is what this target did on its first end-to-end run,
+# against a pin whose floor was set one release too low.
+#
+# So the floor is the version that actually ships the feature, not the version
+# that happened to be current when it was written.
+SDKGEN_MIN := 4.16.0
+
+regen: sdk-src
+	@set -e; \
+	if [ -L "$(SDK_DIR)" ]; then \
+	  echo "regen: $(SDK_DIR) is a symlink, and regenerating through one writes"; \
+	  echo "       the package somewhere else. Node resolves a module's own"; \
+	  echo "       directory through symlinks, so the generator computes its"; \
+	  echo "       destination from where the checkout REALLY is — not from"; \
+	  echo "       here — and \`enclosing\` then permits the result."; \
+	  echo "       SDK_SRC_FROM is for building and linking against a local"; \
+	  echo "       SDK (make sdk-src). To regenerate, use a fetched checkout:"; \
+	  echo "         make sdk-clean && make regen"; \
+	  exit 1; \
+	fi; \
+	echo "regen: building the generator in $(SDK_DIR)/.sdk"; \
+	npm --prefix "$(SDK_DIR)/.sdk" install; \
+	have=$$(node -e "console.log(JSON.parse(require('fs').readFileSync('$(SDK_DIR)/.sdk/node_modules/@voxgig/sdkgen/package.json','utf8')).version)"); \
+	node -e 'const a=process.argv[1].split(".").map(Number),b=process.argv[2].split(".").map(Number); \
+	  for(let i=0;i<3;i++){if(a[i]>b[i])process.exit(0);if(a[i]<b[i])process.exit(1)} process.exit(0)' \
+	  "$$have" "$(SDKGEN_MIN)" || { \
+	    echo "regen: $(SDK_TAG) uses @voxgig/sdkgen $$have, and regenerating from"; \
+	    echo "       inside this repo needs >= $(SDKGEN_MIN) (the generate-time output"; \
+	    echo "       override). Older versions IGNORE it and silently write nothing."; \
+	    echo "       Pin a newer SDK tag, or regenerate from a checkout of the SDK."; \
+	    exit 1; }; \
+	echo "regen: generating"; \
+	cd "$(SDK_DIR)/.sdk" && \
+	  SDKGEN_EXTERNAL='{"seneca-provider":{"path":"../..","enclosing":true}}' \
+	  npm run generate
+	@echo "regen: done — review the diff in this repository"

package/README.md

@@ -114,6 +114,29 @@ Validate the package itself with:
 npx voxgig-sdkgen package check .
 ```
 
+## Releasing — OIDC dispatch, never a local publish
+
+**NOTHING IS PUBLISHED FROM A WORKSTATION.** The release is performed by
+GitHub Actions over OIDC trusted publishing, and the way you start it is a
+workflow dispatch:
+
+```bash
+gh workflow run publish.yml --ref main -f expect_sha=$(git rev-parse HEAD)
+```
+
+Bump the version in **both** `package.json` and `sdkgen-package.json` first,
+on `main`, in a reviewable commit — nothing in the workflow commits. The
+workflow verifies, publishes to npm, then tags `v<version>`.
+
+Never `npm publish` from a checkout: it goes out over a stored token with no
+provenance. The one exception is a package's very first version, which npm
+gives no way to automate — see [`release/README.md`](release/README.md), which
+carries the full record, the `npm trust` registration, and what the 404 at the
+end of a green run actually means.
+
+Never hand a release back as "run this locally yourself". A release is a
+dispatch: prepare the commit, then dispatch the workflow.
+
 ## Provenance
 
 `seneca-provider` was generated from the same trees that shipped inside

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/sdkgen-infrapack",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "Infrastructure-provider targets for the Voxgig SDK Generator: Seneca provider.",
   "type": "commonjs",
   "license": "MIT",
@@ -85,11 +85,11 @@
   ],
   "peerDependencies": {
     "@voxgig/apidef": ">=8.4.0",
-    "@voxgig/sdkgen": ">=4.12.0"
+    "@voxgig/sdkgen": ">=4.16.0"
   },
   "devDependencies": {
     "@voxgig/apidef": ">=8.4.0",
-    "@voxgig/sdkgen": ">=4.12.0",
+    "@voxgig/sdkgen": ">=4.16.0",
     "aontu": ">=0.52",
     "memfs": "4.68.1",
     "typescript": "7.0.2",

package/sdkgen-package.json

@@ -3,9 +3,9 @@
     "package": 1
   },
   "name": "@voxgig/sdkgen-infrapack",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "engines": {
-    "sdkgen": ">=4.12.0"
+    "sdkgen": ">=4.16.0"
   },
   "provides": {
     "target": [