@voxgig/sdkgen-infrapack 0.0.15 → 0.0.16

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

@@ -16,6 +16,11 @@ main: kit: target: 'seneca-provider': {
     test:       { active: false }
   }
 
+  sdk: {
+    package: *'' | string
+    version: *'' | string
+  }
+
   sdk: dep: {
     kind: *'npm' | 'git' | 'release'
     ref: *'' | string

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

@@ -23,7 +23,12 @@ const SdkPin = cmp(function SdkPin(props: any) {
 
   File({ name: 'sdk-pin.json' }, () => {
     Content(JSON.stringify({
-      note: 'GENERATED. The SDK this provider is generated from. ' +
+      note: provider.standalone ?
+        'GENERATED. The SDK this provider depends on and is generated from. ' +
+        '`make sdk-src` fetches it; `make regen` replaces the API definition ' +
+        'and guide in .sdk/ with its own and regenerates this repo. Set the version in ' +
+        '.sdk/model/project.aontu, not in this file.' :
+        '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,
@@ -1718,7 +1723,8 @@ const seneca = Seneca()
       },
     },
   })
-  .use('${provider.pkgName}')
+  .use('${provider.pkgName}'${'' === provider.specBase ?
+      `, { sdk: { base: 'https://${provider.lower}.example.com' } }` : ''})
 
 await seneca.ready()
 
@@ -1734,7 +1740,7 @@ await seneca.ready()
         `'${cparts.map((p: string) => 'some-' + p).join(
           null != subject.idsep && '' !== String(subject.idsep) ?
             String(subject.idsep) : '/')}'` :
-        0 === subject.parents.length ? `'some-id'` :
+        0 === subject.parents.length ? (loadHasKey(subject) ? `'some-id'` : '') :
           `{ ` + subject.parents.map((p: string) => `${jsKey(p)}: 'some-${p}'`).join(', ') +
           `, id: 'some-id' }`
       Content(`const ${subject.name} = await seneca
@@ -1898,7 +1904,10 @@ whose logs cannot be read.
     each(provider.entities, (e: any) => {
       each(e.cmds, (cmd: any) => {
         const c = String(cmd.val$ ?? cmd)
-        Content(`| \`sys:entity,cmd:${c},zone:provider,base:${provider.lower},name:${e.name}\` | ${CMD_DESC[c]}. |
+        const desc = 'save' !== c ? CMD_DESC[c] :
+          !e.ops.includes('update') ? 'Create a record' :
+            !e.ops.includes('create') ? 'Update a record' : CMD_DESC[c]
+        Content(`| \`sys:entity,cmd:${c},zone:provider,base:${provider.lower},name:${e.name}\` | ${desc}. |
 `)
       })
     })
@@ -1978,9 +1987,15 @@ const sdk = seneca.export('${provider.pluginName}/sdk')()
 
 ## Contributing
 
-This plugin is GENERATED. Changes belong in the SDK project's model and
+${provider.standalone ?
+`This plugin is GENERATED, by the builder in \`.sdk/\` from the API definition
+of the SDK it depends on. Changes to the API belong in the SDK project's
+model, this package's own decisions in \`.sdk/model/project.aontu\`, and
+everything else in the components that build this target — anything edited
+elsewhere in this repository is overwritten by the next \`make regen\`.` :
+`This plugin is GENERATED. Changes belong in the SDK project's model and
 components, not here — anything edited in this repository is overwritten by
-the next generation run.
+the next generation run.`}
 
 The [Senecajs org](http://senecajs.org) encourages open participation. If you
 feel you can help in any way, be it with bug reporting, documentation,
@@ -2677,6 +2692,7 @@ const DocHowto = cmp(function DocHowto(props: any) {
   // an absent value to the same thing, so a missing base is treated as absent
   // rather than printed as a default nobody can use.
   const liveBase = provider.liveBase || ''
+  const specBase = provider.specBase || ''
 
   // The same choice the tests and the manual scripts make: fewest parent keys
   // (nothing to arrange), then most cmds. Recipes prefer it, so one entity
@@ -2698,6 +2714,7 @@ const DocHowto = cmp(function DocHowto(props: any) {
   // the API calls it. `apiKey` is that name, for the SDK-direct examples.
   const idf = (_e: any) => 'id'
   const apiKey = (e: any) => e.rk || 'id'
+  const modelsId = (e: any) => null != e.ent?.id || null != (e.ent?.fields || {})[apiKey(e)]
 
   // A parent key's example value. This MIRRORS seedRecord rather than
   // inventing something more readable: the offline recipe below seeds with
@@ -2767,7 +2784,15 @@ const DocHowto = cmp(function DocHowto(props: any) {
 
   const eList = forCmd('list')
   const eLoad = forCmd('load')
-  const eSave = forCmd('save')
+  const forOp = (op: string) => {
+    const able = ents.filter((e: any) => e.ops.includes(op))
+    return able.find((e: any) => e === subject) ||
+      able.find((e: any) => 0 === e.parents.length) ||
+      able[0] || null
+  }
+
+  const eCreate = forOp('create')
+  const eUpdate = forOp('update')
   const eRemove = forCmd('remove')
 
   // Sections as data, so the contents list and the sections cannot disagree.
@@ -2841,53 +2866,63 @@ genuinely wrong.`)
   }
 
 
-  if (null != eSave) {
-    const created = literal(createData(eSave))
+  if (null != eCreate) {
+    const created = literal(createData(eCreate))
+    const updates = eCreate.ops.includes('update')
 
-    sec('Create a record', `\`make$\` builds an entity and \`save$\` writes it. An entity with no id
-is a create:
+    sec('Create a record', `\`make$\` builds an entity and \`save$\` writes it. ${updates ?
+      'An entity with no id\nis a create:' :
+      `The API has no update\nfor a \`${eCreate.name}\`, so \`save$\` always creates one, even from an entity\nthat carries an id:`}
 
 \`\`\`js
-const ${eSave.name} = await seneca
-  .entity('${canon(eSave)}')
+const ${eCreate.name} = await seneca
+  .entity('${canon(eCreate)}')
   .make$(${created})
   .save$()
 
-console.log(${eSave.name}.${idf(eSave)})
+console.log(${eCreate.name}${modelsId(eCreate) ? '.' + idf(eCreate) : ''})
 \`\`\`
-${0 === eSave.parents.length ? '' : `
-Note that \`${eSave.parents.join('`, `')}\` travels in the DATA for a write,
-not in a query: a \`${eSave.name}\` is created inside its parent.
+${0 === eCreate.parents.length ? '' : `
+Note that \`${eCreate.parents.join('`, `')}\` travels in the DATA for a write,
+not in a query: a \`${eCreate.name}\` is created inside its parent.
 `}
-\`save$\` resolves to the record as the API returned it, which is the only
+${modelsId(eCreate) ?
+      `\`save$\` resolves to the record as the API returned it, which is the only
 reliable source of the id. Read it from there rather than predicting it:
 what an API does with an id you supply on create is its own business, and
-several ignore it entirely.`)
+several ignore it entirely.` :
+      `\`save$\` resolves to the record as the API returned it. The API definition
+declares no id for a \`${eCreate.name}\`, so the record is the only place to
+read what identifies one.`}`)
+  }
 
-    const f = changeable(eSave)
 
-    sec('Update a record', `The same call updates. \`save$\` dispatches on the id: an entity carrying
-one is an update, an entity without one is a create. So the safe shape is
+  if (null != eUpdate) {
+    const f = changeable(eUpdate)
+
+    sec('Update a record', `${eUpdate.ops.includes('create') ?
+      'The same call updates. `save$` dispatches on the id: an entity carrying\none is an update, an entity without one is a create.' :
+      `\`save$\` updates: the API has no create for a \`${eUpdate.name}\`.`} So the safe shape is
 load, change, save:
 
-\`\`\`js${eSave.cmds.includes('load') ? `
-const ${eSave.name} = await seneca
-  .entity('${canon(eSave)}')
-  .load$(${oneArgs(eSave)})
+\`\`\`js${eUpdate.cmds.includes('load') ? `
+const ${eUpdate.name} = await seneca
+  .entity('${canon(eUpdate)}')
+  .load$(${oneArgs(eUpdate)})
 ` : `
-const ${eSave.name} = seneca
-  .entity('${canon(eSave)}')
-  .make$(${literal(0 === eSave.parents.length ?
-      { [idf(eSave)]: `${eSave.name}0` } :
-      { ...Object.fromEntries(eSave.parents.map(
-        (k: string) => [k, parentVal(eSave, k)])),
-      [idf(eSave)]: `${eSave.name}0` })})
+const ${eUpdate.name} = seneca
+  .entity('${canon(eUpdate)}')
+  .make$(${literal(0 === eUpdate.parents.length ?
+      { [idf(eUpdate)]: `${eUpdate.name}0` } :
+      { ...Object.fromEntries(eUpdate.parents.map(
+        (k: string) => [k, parentVal(eUpdate, k)])),
+      [idf(eUpdate)]: `${eUpdate.name}0` })})
 `}${null == f ? `
 // change the fields you need
 ` : `
-${eSave.name}.${f.name} = ${newValue(f)}
+${eUpdate.name}.${f.name} = ${newValue(f)}
 `}
-await ${eSave.name}.save$()
+await ${eUpdate.name}.save$()
 \`\`\`
 
 Mutating the record you loaded sends it as it stood plus your change, so
@@ -3027,13 +3062,16 @@ constructor, so \`base\` chooses the host:
 })
 \`\`\`
 
-${'' === liveBase ?
+${'' === specBase ?
     `The API definition declares no server, so there is no default worth
 relying on: set \`base\` explicitly, or run against the mock instead (see
 [${OFFLINE_TITLE}](${anchor(OFFLINE_TITLE)})).` :
-    `The SDK's own default is \`${liveBase}\`, which is where the
+    specBase === liveBase ?
+      `The SDK's own default is \`${liveBase}\`, which is where the
 companion test server listens, so local development usually needs no
-\`base\` at all.`}`)
+\`base\` at all.` :
+      `The SDK's own default is \`${specBase}\`, the server the API definition
+declares, so \`base\` is needed only to reach another one.`}`)
 
 
   if (!provider.authActive) {
@@ -3321,10 +3359,15 @@ $ npm run repo-publish
 Only \`dist\`, the TypeScript sources and the licence file are published;
 the test suite and its build output stay in the repository.
 
-Before publishing, check that \`package.json\` still depends on the
+${'npm' === provider.sdkDepKind ?
+    `Before publishing, check that \`package.json\` still depends on the
 published SDK by version range and not on a local path: a \`file:\`
 dependency left behind from local development installs perfectly on your
-own machine and cannot be resolved by anybody else.
+own machine and cannot be resolved by anybody else.` :
+    `Publish the SDK to npm first. \`package.json\` depends on it as
+\`${provider.sdkDep}\`, which everyone installing this package would
+have to fetch${'git' === provider.sdkDepKind ? ' with git' : ''}. Then drop \`sdk.dep\` from the model, regenerate,
+and check that the dependency is a version range.`}
 
 One last thing: this repository is GENERATED from the ${provider.api} API
 model by [@voxgig/sdkgen](https://github.com/voxgig/sdkgen). An edit made
@@ -3501,6 +3544,14 @@ Seneca({ legacy: false })
     if (live) {
       Content(`  .use('${provider.pkgName}', { sdk: { base: '${provider.liveBase}' } })
 \`\`\`
+`)
+    }
+    else if ('' !== provider.specBase) {
+      Content(`  .use('${provider.pkgName}')
+\`\`\`
+
+The SDK's default base URL is \`${provider.specBase}\`, the server the
+${provider.api} definition declares. Pass \`sdk: { base }\` to reach another.
 `)
     }
     else {
@@ -3531,8 +3582,8 @@ Any option the \`${provider.sdkClass}\` constructor accepts:
 
 | Key | Effect |
 | --- | ------ |
-| \`base\` | Base URL for API requests. ${live ?
-      `The SDK's own default is \`${provider.liveBase}\`.` :
+| \`base\` | Base URL for API requests. ${'' !== provider.specBase ?
+      `The SDK's own default is \`${provider.specBase}\`, the server the API definition declares.` :
       'There is no default: this API declares no server, so it must be set.'} |
 | \`prefix\` / \`suffix\` | URL fragments placed around the path. |
 | \`headers\` | Headers sent on every request. These win over the \`authorization\` header the provider adds from a configured key. |
@@ -3618,7 +3669,9 @@ before any request is made, rather than issuing one that would 404.
 `)
       }
       if (e.cmds.includes('load')) {
-        Content(`| \`load$(q)\` | ${reqd([...e.parents, 'id'])} | One \`${e.name}\`, or \`null\` if not found. |
+        Content(loadHasKey(e) ?
+          `| \`load$(q)\` | ${reqd([...e.parents, 'id'])} | One \`${e.name}\`, or \`null\` if not found. |
+` : `| \`load$(q)\` | ${0 < e.parents.length ? reqd(e.parents) : 'nothing: the route names no record'} | The one \`${e.name}\`, or \`null\` when \`id\` names one it does not carry. |
 `)
       }
       if (e.cmds.includes('save')) {
@@ -3636,7 +3689,8 @@ before any request is made, rather than issuing one that would 404.
 
       if ('id' !== apiKeyOf(e)) {
         Content(`
-The API addresses \`${e.name}\` records by \`${apiKeyOf(e)}\`; the provider
+The API ${e.ops.some((op: string) => ['load', 'remove', 'update'].includes(op)) ?
+          'addresses' : 'identifies'} \`${e.name}\` records by \`${apiKeyOf(e)}\`; the provider
 carries that value as the entity's \`id\`, so every query and entity above
 uses \`id\`. A record the API returns with an unrelated \`id\` of its own
 ${false === e.parkfree ?
@@ -3661,7 +3715,7 @@ also defines are passed through unchanged in both directions.
 | ----- | ---- | ----- |
 `)
         each(e.fields, (f: any) => {
-          Content(`| \`${f.name}\` | ${f.kind} | ${f.name === (e.rk || 'id') ?
+          Content(`| \`${f.name}\` | ${f.kind}${f.nullable ? ' or null' : ''} | ${f.name === (e.rk || 'id') ?
             ('id' === f.name ? 'Id field.' : 'API key; carried as the entity\'s `id`.') :
             e.parents.includes(f.name) ? ('' === f.parentEntity ?
               'Parent key. Required by every command.' :
@@ -4440,11 +4494,16 @@ rather than as a surprise in production.
 `)
 
     if ('' === provider.liveBase) {
-      Content(`The API definition declares no server, so this plugin has no default host: the
+      Content(`${'' === provider.specBase ?
+        `The API definition declares no server, so this plugin has no default host: the
 base URL arrives through the \`sdk.base\` option, supplied by whoever configures
 the plugin for a particular deployment. The tests therefore run entirely
 against the SDK's mock transport, which is the one host that is always
-available.
+available.` :
+        `The SDK's default host is \`${provider.specBase}\`, the server the API
+definition declares, and the \`sdk.base\` option points the plugin at another.
+Nothing declares a test server, so the tests run entirely against the SDK's
+mock transport, which is the one host that is always available.`}
 
 
 `)
@@ -4476,7 +4535,10 @@ that has to be applied again, silently, forever.
 
 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*
+together with the sdkgen component that emits this target.${provider.standalone ? `
+This repository builds itself: the builder in \`.sdk/\` carries a copy of that
+SDK's API definition, which \`make regen\` refreshes from the fetched source,
+and generation refuses to write when the copy no longer matches it.` : ''} 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

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

@@ -1,7 +1,7 @@
 import {
   cmp, each,
   File, Content, Copy, Folder,
-  entityCollection, entityOps, entityIdField, entityClassName,
+  entityCollection, entityOps, entityIdField, entityDataIdField, entityClassName,
   entityActions,
   opRequestShape, opParams, ownPoint, entityPath,
   collectDeps, repoInfo, packageName, packageVersion, apiName, envName,
@@ -20,6 +20,10 @@ import {
   Tests, Scripts, Workflow, Readme, Docs, SdkPin, SDK_SRC_DIR,
 } from './Extras_seneca-provider'
 import { Gitignore } from './Gitignore_seneca-provider'
+import { Makefile } from './Makefile_seneca-provider'
+import {
+  standaloneBuilder, sdkIdentity, checkSdkSource,
+} from './Standalone_seneca-provider'
 
 
 
@@ -208,7 +212,7 @@ function recordKey(ent: any): string {
     }
   }
 
-  return '' !== fallback ? fallback : 'id'
+  return '' !== fallback ? fallback : (entityDataIdField(ent) || 'id')
 }
 
 
@@ -278,9 +282,18 @@ function parentKeys(ent: any): string[] {
 }
 
 
+const sentinelKey = (type: any): string =>
+  String(type ?? '').replace(/[`$]/g, '').trim().toUpperCase()
+
+const unionMembers = (type: any): any[] =>
+  Array.isArray(type) && 'ONE' === sentinelKey(type[0]) && Array.isArray(type[1]) ?
+    type[1] : []
+
+
 function fieldKind(type: any): string {
   if (Array.isArray(type)) {
-    return 'string'
+    const member = unionMembers(type).find((m: any) => 'NULL' !== sentinelKey(m))
+    return null == member ? 'string' : fieldKind(member)
   }
 
   const t = String(type || '').toUpperCase()
@@ -294,6 +307,11 @@ function fieldKind(type: any): string {
 }
 
 
+function fieldNullable(type: any): boolean {
+  return unionMembers(type).some((m: any) => 'NULL' === sentinelKey(m))
+}
+
+
 function parentEntityOf(key: string, names: string[]): string {
   const stem = key.replace(/_id$/, '')
   return names.includes(stem) ? stem : ''
@@ -326,8 +344,10 @@ const Main = cmp(function Main(props: any) {
   const { target, ctx$ } = props
   const { model } = ctx$
 
+  const standalone = standaloneBuilder(target)
+
   const targets = model.main[KIT].target || {}
-  if (null == targets.ts) {
+  if (!standalone && null == targets.ts) {
     throw new SdkGenError(
       'seneca-provider requires the `ts` target in the same SDK: it imports ' +
       'the TypeScript SDK that `ts` generates. Add it with:\n' +
@@ -347,8 +367,7 @@ const Main = cmp(function Main(props: any) {
   // included, so the two can never disagree.
   // The TypeScript SDK this provider WRAPS — a different target, so it
   // keeps its own name and does not follow this provider's alias.
-  const sdkPkg = packageName(model, 'npm')
-  const sdkVersion = packageVersion(model, 'ts')
+  const { sdkPkg, sdkVersion } = sdkIdentity(model, target)
 
   const entityColl = entityCollection(model)
 
@@ -434,6 +453,7 @@ const Main = cmp(function Main(props: any) {
             .map((f: any) => ({
               name: f.n,
               kind: fieldKind(f.t),
+              nullable: fieldNullable(f.t),
               parentEntity: parentEntityOf(f.n, entityNames),
             }))
 
@@ -444,6 +464,7 @@ const Main = cmp(function Main(props: any) {
               req.push({
                 name: key,
                 kind: 'string',
+                nullable: false,
                 parentEntity: parentOf[key],
               })
             }
@@ -510,6 +531,7 @@ const Main = cmp(function Main(props: any) {
     Name, lower, ENV, sdkClass, pluginName, fileBase,
     sdkPkg, sdkVersion, entities,
     sdkDep,
+    standalone,
     // Whether that dependency comes from outside a registry. The generated
     // CI note says so, because "npm install is all you need" stops being
     // true the moment git or a tarball URL is in the path.
@@ -531,6 +553,8 @@ const Main = cmp(function Main(props: any) {
     version: packageVersion(model, target.name),
     liveBase,
     liveApp,
+    // The server the API definition declares, which is the SDK's own default.
+    specBase,
     publisher: PUBLISHER,
     publisherUrl: PUBLISHER_URL,
     probePath: (entities.find((e: any) =>
@@ -549,6 +573,10 @@ const Main = cmp(function Main(props: any) {
     authPrefix: resolveAuthPrefix(model),
   }
 
+  if (standalone) {
+    checkSdkSource(ctx$, provider, model)
+  }
+
   // `.gitignore` is EMITTED rather than copied — npm strips that filename
   // from the tarball, so as a template it reached only checkout users. See
   // Gitignore_seneca-provider. Called before the Copy, as every language
@@ -560,6 +588,7 @@ const Main = cmp(function Main(props: any) {
     replace: { ...ctx$.stdrep },
   })
 
+  Makefile({ provider })
   SdkPin({ provider })
   PackageJson({ provider, target })
   ProviderSource({ provider })
@@ -1218,7 +1247,12 @@ ${actionBranch('load',
             `        const hit = await ornull(() => this.shared.sdk.${e.acc}()[op$](${aq}))
         return null == hit ? null : entize(${out('hit')})
 `)}${guard('load', 'q')}${splitLine('load')}      const res = await ornull(() => this.shared.sdk.${e.acc}().load(${sdkArg('load')}))
-      return null == res ? null : entize(${out('res', loadVals)})
+${0 < addressKeys(e.ent, 'load').length || 0 < eparts.length ? '' :
+            `      // The route names no record, so an id finds only the record carrying it.
+      if (null != res && null != q.id && String(${jsProp('plain(res)', rk)}) !== String(q.id)) {
+        return null
+      }
+`}      return null == res ? null : entize(${out('res', loadVals)})
     }
 
 `)
@@ -1268,7 +1302,12 @@ ${dropPark}
       // which matches a request against a stored record, then looked for a
       // record whose own \`id\` was that joined string and found none.
       delete data.id
-` : !keyed ? '' : `
+` : !keyed ? '' : hasCreate && !hasUpdate && true !== e.rkoncreate ? `
+      // The API assigns a ${e.name}'s \`${rk}\`, and a create names no record, so
+      // Seneca's \`id\` is not sent: the id is read back from the response.
+      const key: any = null
+${dropPark}      delete data.id
+` : `
       // This API keys a ${e.name} by \`${rk}\`; Seneca carries it as \`id\`.
       // The key goes on the body under the API's own name, where the route
       // reads it, and into the match, which the SDK consults first.
@@ -1369,9 +1408,10 @@ ${provider.authActive ? `
     // the SDK was constructed with NO credential at all — the request went
     // out unauthenticated and failed much later as a 401 or a 404 on
     // anything private, with nothing at startup to point at the cause.
-    // \`apikey\` wins when both are set, so a config that has migrated is
-    // unaffected.
-    const apikey = res?.keymap?.apikey?.value ?? res?.keymap?.api?.value
+    // \`apikey\` wins when both are set and it is not empty, so a config that
+    // has migrated is unaffected.
+    const apikey = [res?.keymap?.apikey?.value, res?.keymap?.api?.value]
+      .find((value: any) => null != value && '' !== value)
 
     // Hand the credential to the SDK as \`apikey\`, NOT as an authorization
     // HEADER. The SDK's own auth stage owns that header: it reads

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

@@ -0,0 +1,216 @@
+import {
+  Content,
+  File,
+  cmp,
+} from '@voxgig/sdkgen'
+
+
+const HEAD = `# GENERATED by @voxgig/sdkgen. Do not edit.
+
+.PHONY: all build test clean reset sdk-src sdk-clean regen
+
+all: build test
+
+build:
+\tnpm run build
+
+test:
+\tnpm test
+
+clean:
+\trm -rf dist dist-test .tsbuildinfo
+
+reset:
+\tnpm run reset
+
+`
+
+
+const INTRO_SDK = `# ---------------------------------------------------------------------------
+# 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.
+# ---------------------------------------------------------------------------`
+
+
+// A provider whose builder is its own repository's .sdk/ (`output: root`).
+const INTRO_SELF = `# ---------------------------------------------------------------------------
+# THIS REPOSITORY IS GENERATED, BY ITS OWN BUILDER IN .sdk/.
+#
+# The builder generates this package and nothing else. Its API definition
+# and guide are the SDK's: everything below fetches the SDK named in
+# sdk-pin.json, and \`make regen\` replaces them with its own before
+# generating, so the package is built from the same model as the SDK version
+# it depends on.
+#
+# 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.
+# ---------------------------------------------------------------------------`
+
+
+const FETCH = `
+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:
+\t@set -e; \\
+\ttest -n "$(SDK_REPO)" || { echo "sdk-src: no repo in $(SDK_PIN)"; exit 1; }; \\
+\ttest -n "$(SDK_TAG)" || { echo "sdk-src: no tag in $(SDK_PIN)"; exit 1; }; \\
+\tif [ -n "$(SDK_SRC_FROM)" ]; then \\
+\t  echo "sdk-src: using $(SDK_SRC_FROM) (not fetching)"; \\
+\t  rm -rf "$(SDK_DIR)"; mkdir -p "$$(dirname "$(SDK_DIR)")"; \\
+\t  ln -s "$$(cd "$(SDK_SRC_FROM)" && pwd)" "$(SDK_DIR)"; \\
+\t  exit 0; \\
+\tfi; \\
+\tif [ -L "$(SDK_DIR)" ]; then \\
+\t  echo "sdk-src: $(SDK_DIR) links to $$(readlink "$(SDK_DIR)"), which is left as it is;"; \\
+\t  echo "         make sdk-clean first to fetch $(SDK_TAG) instead"; \\
+\t  exit 0; \\
+\tfi; \\
+\tif [ -d "$(SDK_DIR)/.git" ]; then \\
+\t  echo "sdk-src: fetching $(SDK_TAG) in $(SDK_DIR)"; \\
+\t  git -C "$(SDK_DIR)" fetch --depth 1 origin "refs/tags/$(SDK_TAG):refs/tags/$(SDK_TAG)" 2>/dev/null || \\
+\t    git -C "$(SDK_DIR)" fetch origin "refs/tags/$(SDK_TAG):refs/tags/$(SDK_TAG)"; \\
+\t  git -C "$(SDK_DIR)" checkout -q "refs/tags/$(SDK_TAG)"; \\
+\telse \\
+\t  echo "sdk-src: cloning $(SDK_REPO) at $(SDK_TAG) into $(SDK_DIR)"; \\
+\t  rm -rf "$(SDK_DIR)"; mkdir -p "$$(dirname "$(SDK_DIR)")"; \\
+\t  git clone --depth 1 --branch "$(SDK_TAG)" "$(SDK_REPO).git" "$(SDK_DIR)"; \\
+\tfi; \\
+\techo "sdk-src: $(SDK_DIR) is at $(SDK_TAG)"
+
+# Removes the fetched checkout AND the folder that held it. \`rm -rf\` on the
+# checkout alone left an empty \`.sdksrc/\` behind — gitignored, so harmless,
+# but it makes \`sdk-clean\` look like it did not finish. rmdir rather than
+# another rm -rf: if anything else is in there, someone put it there, and
+# removing it is not this target's business.
+sdk-clean:
+\trm -rf "$(SDK_DIR)"
+\t@rmdir "$$(dirname "$(SDK_DIR)")" 2>/dev/null || true
+`
+
+
+const REGEN_SDK = `# 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
+\t@set -e; \\
+\tif [ -L "$(SDK_DIR)" ]; then \\
+\t  echo "regen: $(SDK_DIR) is a symlink, and regenerating through one writes"; \\
+\t  echo "       the package somewhere else. Node resolves a module's own"; \\
+\t  echo "       directory through symlinks, so the generator computes its"; \\
+\t  echo "       destination from where the checkout REALLY is — not from"; \\
+\t  echo "       here — and \\\`enclosing\\\` then permits the result."; \\
+\t  echo "       SDK_SRC_FROM is for building and linking against a local"; \\
+\t  echo "       SDK (make sdk-src). To regenerate, use a fetched checkout:"; \\
+\t  echo "         make sdk-clean && make regen"; \\
+\t  exit 1; \\
+\tfi; \\
+\techo "regen: building the generator in $(SDK_DIR)/.sdk"; \\
+\tnpm --prefix "$(SDK_DIR)/.sdk" install; \\
+\thave=$$(node -e "console.log(JSON.parse(require('fs').readFileSync('$(SDK_DIR)/.sdk/node_modules/@voxgig/sdkgen/package.json','utf8')).version)"); \\
+\tnode -e 'const a=process.argv[1].split(".").map(Number),b=process.argv[2].split(".").map(Number); \\
+\t  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)' \\
+\t  "$$have" "$(SDKGEN_MIN)" || { \\
+\t    echo "regen: $(SDK_TAG) uses @voxgig/sdkgen $$have, and regenerating from"; \\
+\t    echo "       inside this repo needs >= $(SDKGEN_MIN) (the generate-time output"; \\
+\t    echo "       override). Older versions IGNORE it and silently write nothing."; \\
+\t    echo "       Pin a newer SDK tag, or regenerate from a checkout of the SDK."; \\
+\t    exit 1; }; \\
+\techo "regen: generating"; \\
+\tcd "$(SDK_DIR)/.sdk" && \\
+\t  SDKGEN_EXTERNAL='{"seneca-provider":{"path":"../..","enclosing":true}}' \\
+\t  npm run generate
+\t@echo "regen: done — review the diff in this repository"
+`
+
+
+const REGEN_SELF = `# Regenerate this repository with its own builder.
+#
+# The API definition and guide are replaced by the SDK source's first, so the
+# builder generates from the SDK's model at the pinned tag, and generation
+# checks the result against that source before writing. A linked checkout
+# (SDK_SRC_FROM) is read as it is, and only this repository is written.
+#
+# To move to a newer SDK, set its version in .sdk/model/project.aontu and
+# fetch that tag as you regenerate:
+#
+#   make regen SDK_TAG=v1.2.3
+regen: sdk-src
+\t@set -e; \\
+\ttest -f .sdk/package.json || { echo "regen: no builder at .sdk/"; exit 1; }; \\
+\tfor d in def model/guide; do \\
+\t  test -d "$(SDK_DIR)/.sdk/$$d" || { echo "regen: no $(SDK_DIR)/.sdk/$$d"; exit 1; }; \\
+\tdone; \\
+\techo "regen: replacing the API definition and guide with those in $(SDK_DIR)"; \\
+\tfor d in def model/guide; do \\
+\t  rm -rf ".sdk/$$d"; mkdir -p ".sdk/$$d"; cp -R "$(SDK_DIR)/.sdk/$$d/." ".sdk/$$d/"; \\
+\tdone; \\
+\techo "regen: installing the builder"; \\
+\tcd .sdk && npm install && \\
+\techo "regen: generating" && \\
+\tnpm run generate
+\t@echo "regen: done — review the diff in this repository"
+`
+
+
+const Makefile = cmp(function Makefile(props: any) {
+  const { provider } = props
+
+  File({ name: 'Makefile' }, () => {
+    Content([
+      HEAD,
+      provider.standalone ? INTRO_SELF : INTRO_SDK,
+      FETCH,
+      provider.standalone ? REGEN_SELF : REGEN_SDK,
+    ].join('\n'))
+  })
+})
+
+
+export {
+  Makefile,
+}

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

@@ -0,0 +1,201 @@
+import Path from 'node:path'
+
+import {
+  packageName, packageVersion,
+  SdkGenError,
+} from '@voxgig/sdkgen'
+
+import {
+  KIT,
+} from '@voxgig/apidef'
+
+
+// `output: root: true` means this repository's own `.sdk/` is the builder:
+// the SDK is released elsewhere, and is not a target of this project.
+function standaloneBuilder(target: any): boolean {
+  return true === target?.output?.root
+}
+
+
+function sdkIdentity(model: any, target: any):
+  { sdkPkg: string, sdkVersion: string } {
+  const sdk = target?.sdk || {}
+  const pkg = String(sdk.package || '')
+  const version = String(sdk.version || '')
+  const hasTs = null != model?.main?.[KIT]?.target?.ts
+
+  if (!standaloneBuilder(target)) {
+    if ('' !== pkg || '' !== version) {
+      throw new SdkGenError(
+        target.name + ': `sdk.package` and `sdk.version` apply only to a ' +
+        'provider generated at the root of its own repository (`output: ' +
+        'root: true`). Generated from the SDK project, the SDK is its `ts` ' +
+        'target: set `main.' + KIT + '.target.ts.publish.version` instead.')
+    }
+    return { sdkPkg: packageName(model, 'npm'), sdkVersion: packageVersion(model, 'ts') }
+  }
+
+  if ('' === version && !hasTs) {
+    throw new SdkGenError(
+      target.name + ': name the SDK version this provider depends on, as ' +
+      '`main.' + KIT + '.target.' + target.name + '.sdk.version`. Its ' +
+      'builder has no `ts` target to read it from, and a default would pin ' +
+      'whatever version it happens to be.')
+  }
+
+  return {
+    sdkPkg: '' !== pkg ? pkg : packageName(model, 'npm'),
+    sdkVersion: '' !== version ? version : packageVersion(model, 'ts'),
+  }
+}
+
+
+// What the SDK was generated from and the provider reads: titles,
+// descriptions and contract metadata are left out.
+const FIELD_KEYS = ['n', 't', 'r', 'a', 'ro', 'wo', 'fo']
+const POINT_KEYS = ['a', 'k', 'm', 'o', 's', 'r', 't', 'g', 'q', 'gq']
+
+function pick(obj: any, keys: string[]): Record<string, any> {
+  const out: Record<string, any> = {}
+  for (const key of keys) {
+    if (undefined !== obj?.[key]) {
+      out[key] = obj[key]
+    }
+  }
+  return out
+}
+
+
+// Keyed by path under `main.kit`, so a difference names where to look.
+function apiSurface(model: any): Record<string, any> {
+  const kit = model?.main?.[KIT] || {}
+  const out: Record<string, any> = {
+    info: {
+      auth: kit.info?.auth,
+      security: kit.info?.security,
+      servers: (kit.info?.servers || []).map((server: any) => pick(server, ['url'])),
+    },
+    config: { auth: kit.config?.auth },
+  }
+
+  const coll = kit.entity || {}
+  for (const name of Object.keys(coll).sort()) {
+    const ent = coll[name]
+    if (null != ent && false !== ent.active) {
+      out['entity.' + name] = {
+        id: ent.id,
+        alias: ent.alias,
+        relations: { ancestors: ent.relations?.ancestors },
+        fields: Object.fromEntries(Object.entries(ent.fields || {})
+          .map(([key, field]) => [key, pick(field, FIELD_KEYS)])),
+        op: Object.fromEntries(Object.entries(ent.op || {})
+          .map(([key, op]: [string, any]) => [key, {
+            input: op?.input,
+            points: (op?.points || []).map((point: any) => pick(point, POINT_KEYS)),
+          }])),
+      }
+    }
+  }
+
+  return out
+}
+
+
+function brief(value: any): string {
+  const text = undefined === value ? 'absent' : JSON.stringify(value)
+  return 60 < text.length ? text.slice(0, 57) + '...' : text
+}
+
+
+// Keys ending in `$` are the generator's marks, present only on a live model.
+function differences(here: any, there: any, path: string, out: string[]): void {
+  const node = (value: any) => null != value && 'object' === typeof value
+  if (node(here) && node(there) && Array.isArray(here) === Array.isArray(there)) {
+    const keys = Array.isArray(here) ?
+      Array.from({ length: Math.max(here.length, there.length) }, (_, i) => i) :
+      [...new Set([...Object.keys(here), ...Object.keys(there)])]
+        .filter((key) => !key.endsWith('$')).sort()
+    for (const key of keys) {
+      differences(here[key], there[key], Array.isArray(here) ?
+        path + '[' + key + ']' : path + '.' + key, out)
+    }
+  }
+  else if (JSON.stringify(here) !== JSON.stringify(there)) {
+    out.push(path + ': here ' + brief(here) + ', SDK ' + brief(there))
+  }
+}
+
+
+// The builder carries its own copy of the SDK's API definition, right only
+// while it matches the SDK at the version depended on. `make sdk-src` fetches
+// that SDK, whose compiled model is the comparison.
+function checkSdkSource(ctx$: any, provider: any, model: any): void {
+  const fs = ctx$.fs()
+  const rel = provider.sdkSrc + '/.sdk/model/sdk.json'
+  const file = Path.join(ctx$.folder || '.', rel)
+
+  if (!fs.existsSync(file)) {
+    ctx$.log?.warn?.({
+      point: 'sdk-source-unchecked', file: rel,
+      note: 'seneca-provider: ' + rel + ' is absent, so this model was NOT ' +
+        'checked against ' + provider.sdkPkg + ' ' + provider.sdkVersion +
+        '. `make sdk-src` fetches it.'
+    })
+    return
+  }
+
+  const sdk = JSON.parse(String(fs.readFileSync(file, 'utf8')))
+  const problems: string[] = []
+
+  // The SDK's own manifest, when fetched: this builder's naming rule need not
+  // be the one that built the SDK.
+  const manifestFile = Path.join(ctx$.folder || '.', provider.sdkSrc, 'ts', 'package.json')
+  const manifest = fs.existsSync(manifestFile) ?
+    JSON.parse(String(fs.readFileSync(manifestFile, 'utf8'))) : {}
+
+  const sdkVersion = String(manifest.version || packageVersion(sdk, 'ts'))
+  if (sdkVersion !== provider.sdkVersion) {
+    problems.push('version: this provider depends on ' + provider.sdkVersion +
+      ', the fetched SDK is ' + sdkVersion +
+      ' (make regen SDK_TAG=v' + provider.sdkVersion + ')')
+  }
+
+  const sdkPkg = String(manifest.name || packageName(sdk, 'npm'))
+  if (sdkPkg !== provider.sdkPkg) {
+    problems.push('package: this provider depends on ' + provider.sdkPkg +
+      ', the fetched SDK is ' + sdkPkg)
+  }
+
+  const here = apiSurface(model)
+  const there = apiSurface(sdk)
+
+  for (const part of [...new Set([...Object.keys(here), ...Object.keys(there)])].sort()) {
+    const found: string[] = []
+    differences(here[part], there[part], part, found)
+    problems.push(...found.slice(0, 5))
+    if (5 < found.length) {
+      problems.push(part + ': and ' + (found.length - 5) + ' more')
+    }
+  }
+
+  if (0 < problems.length) {
+    throw new SdkGenError(
+      'seneca-provider: this builder\'s model does not match the SDK it ' +
+      'depends on, as fetched to ' + provider.sdkSrc + ' (paths under main.' +
+      KIT + '):\n  ' +
+      problems.join('\n  ') +
+      '\n`make regen` replaces the API definition and guide in .sdk/ with the ' +
+      'SDK\'s before generating. A difference that remains comes from a decision in ' +
+      'the SDK project\'s own model, to be declared the same way in ' +
+      '.sdk/model/project.aontu, or from an @voxgig/apidef version other ' +
+      'than the one in the SDK\'s .sdk/package.json.')
+  }
+}
+
+
+export {
+  standaloneBuilder,
+  sdkIdentity,
+  apiSurface,
+  checkSdkSource,
+}

package/README.md

@@ -27,7 +27,9 @@ sdkgen repository.
 
 These are consumer targets: they switch every standard generation phase off and
 emit their whole package from `Main`, and each one fails without the target it
-wraps, deliberately. Add `ts` to your project before `seneca-provider`.
+wraps, deliberately. Add `ts` to your project before `seneca-provider`. The
+one exception is a provider that carries its own builder (below), which names
+the SDK it wraps instead.
 
 There is no manifest field for that requirement. Nothing in
 `sdkgen-package.json` says "this target needs that one", so this paragraph and
@@ -84,6 +86,75 @@ first look at the output.
 Set that in `model/project.aontu`, not in the target's own file — `target add`
 overwrites the latter.
 
+## Or the provider carries its own builder
+
+The provider repository can instead hold a `.sdk/` of its own, which generates
+the provider and nothing else, and leaves the SDK repository untouched. Its
+`model/project.aontu` says so, and the standard `Root` that create-sdkgen
+scaffolds reads it:
+
+```
+main: kit: phase: top: active: false
+main: kit: phase: build: active: false
+main: kit: doc: active: false
+main: kit: target: 'seneca-provider': output: root: true
+main: kit: target: 'seneca-provider': sdk: version: '0.0.1'
+```
+
+`output: root: true` generates the provider at the repository root, and is how
+this target knows the builder is the provider's own. That builder has no `ts`
+target, so it names the SDK itself: `sdk.version` is required, and
+`sdk.package` overrides the derived package name. Both are refused in an SDK
+project, where the `ts` target is the SDK.
+
+The builder carries a copy of the SDK's API definition and guide. `make regen`
+replaces them with those of the SDK fetched at the tag in `sdk-pin.json` before
+generating. Generation then refuses to write when the builder's model and that
+SDK's compiled model differ in what the SDK was generated from: an entity, an
+operation's routes, parameters and actions, a field's type or requiredness, the
+identity, the ancestors, the authentication or the servers. Titles and
+descriptions are not compared. It also refuses when the package name or version
+differ from the SDK's own `ts/package.json`, which is read rather than the name
+re-derived, because the SDK's generator may name packages by a rule this
+builder's does not share. Generated without the SDK fetched, it warns that the
+check did not run.
+
+A symlinked SDK checkout, from `make sdk-src SDK_SRC_FROM=<path>`, is read as
+it is: `make sdk-src` never fetches or checks out a tag inside one.
+
+To move to a newer SDK, set `sdk.version` and fetch its tag as you regenerate:
+
+```bash
+make regen SDK_TAG=v0.0.2
+```
+
+## An SDK that is not on npm yet
+
+The generated `package.json` depends on the SDK by version range, which
+installs only once the SDK is published. Until then, `sdk.dep` points it
+elsewhere:
+
+| `sdk.dep` | The dependency |
+|---|---|
+| `kind: 'release', ref: 'v1.0.0'` | the `npm pack` tarball attached to that GitHub release |
+| `kind: 'git', ref: '<tag>'` | `github:<owner>/<repo>#<tag>`, installed from the root of that tag's tree |
+| `spec: '<anything>'` | the value, verbatim |
+
+npm cannot install a package from a subfolder of a git repository, and an
+sdkgen SDK keeps its TypeScript package in `ts/`. A git dependency therefore
+needs a tag whose tree is that folder, cut in the SDK repository:
+
+```bash
+git tag ts-v1.0.0 $(git commit-tree HEAD:ts -p HEAD -m "ts/ at v1.0.0")
+git push origin ts-v1.0.0
+```
+
+and then `sdk: dep: { kind: 'git', ref: 'ts-v1.0.0' }`. The tag carries what
+the folder holds, so an SDK that commits `ts/dist` needs nothing built on
+install. The generated CI passes `--allow-git=all`, which npm 12 needs for a
+git dependency, and so would anyone installing a published provider that
+depends on one: publish the SDK to npm before the provider.
+
 ## Parity
 
 Every target here declares `CONSUMER`. That is not a coverage tier alongside

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/sdkgen-infrapack",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "Infrastructure-provider targets for the Voxgig SDK Generator: Seneca provider.",
   "type": "commonjs",
   "license": "MIT",

package/sdkgen-package.json

@@ -3,7 +3,7 @@
     "package": 1
   },
   "name": "@voxgig/sdkgen-infrapack",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "engines": {
     "sdkgen": ">=4.25.0"
   },

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

@@ -1,131 +0,0 @@
-# GENERATED by @voxgig/sdkgen. Do not edit.
-
-.PHONY: all build test clean reset sdk-src sdk-clean regen
-
-all: build test
-
-build:
-	npm run build
-
-test:
-	npm test
-
-clean:
-	rm -rf dist dist-test .tsbuildinfo
-
-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)"
-
-# Removes the fetched checkout AND the folder that held it. `rm -rf` on the
-# checkout alone left an empty `.sdksrc/` behind — gitignored, so harmless,
-# but it makes `sdk-clean` look like it did not finish. rmdir rather than
-# another rm -rf: if anything else is in there, someone put it there, and
-# removing it is not this target's business.
-sdk-clean:
-	rm -rf "$(SDK_DIR)"
-	@rmdir "$$(dirname "$(SDK_DIR)")" 2>/dev/null || true
-
-# 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"