@voxgig/create-sdkgen 0.28.0 → 0.29.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/create-sdkgen",
-  "version": "0.28.0",
+  "version": "0.29.1",
   "main": "dist/create-sdkgen.js",
   "type": "commonjs",
   "types": "dist/create-sdkgen.d.ts",
@@ -47,7 +47,8 @@
     "dist",
     "bin",
     "project",
-    "LICENSE"
+    "LICENSE",
+    "README.md"
   ],
   "devDependencies": {
     "@types/node": "26.1.2",

package/project/standard/.sdk/admin/README.md

@@ -38,7 +38,9 @@ test, and the only symptom is a tree that disagrees with the model:
   anything whose output might be committed.
 
 The script deletes every target tree, regenerates, and reports what differs —
-which is the only way to see output the generator no longer emits. It refuses
+which is the only way to see output the generator no longer emits. A target
+generated at the project root (`output: root: true`) owns every tracked file
+outside `.sdk/`, so those are what it deletes for that target. It refuses
 to run on a dirty tree, restores the target's own build artifacts and
 lockfiles (which the generator never writes), and leaves the regenerated tree
 in place so the diff can be read.
@@ -60,7 +62,29 @@ The setup script configures GitHub Actions as the publishing source. It does
 not commit, push, merge, or deploy. Push the documentation workflow and project
 changes to its configured deployment branch to publish the website.
 
+When a target publishes to npm, sdkgen generates `setup-npm-trust.sh` here.
+For a repository on `github.com`, it registers each npm publish workflow as
+the trusted publisher of its package, from the same model the workflows are
+generated from, and leaves a package that is already set up alone:
+
+```sh
+.sdk/admin/setup-npm-trust.sh --dry-run
+.sdk/admin/setup-npm-trust.sh
+.sdk/admin/setup-npm-trust.sh --check
+```
+
+`--check` changes nothing and exits non-zero on any difference from what the
+workflows need, including a trusted publisher that no workflow names;
+`--replace` revokes those. It needs an npm login with publish rights. For a
+repository hosted anywhere else, npm cannot trust GitHub Actions, so the script
+says so and exits non-zero.
+
+npm offers trusted publishing only for a package that already has a version,
+so a new package's first version is published by hand, as `.sdk/PUBLISHING.md`
+describes. Run the script straight after; every later release goes through the
+generated workflow.
+
 The status launcher and the drift check come from create-sdkgen; the status
-reporting code comes from sdkgen. Docgen owns the generated Pages setup
-script. Put project-specific administration scripts beside them with
-different names.
+reporting code and the npm trust script come from sdkgen. Docgen owns the
+generated Pages setup script. Put project-specific administration scripts
+beside them with different names.

package/project/standard/.sdk/admin/check-drift.sh

@@ -52,17 +52,34 @@ if [[ -n "$(git status --porcelain)" ]]; then
   exit 2
 fi
 
-targets="$(node -e '
-  const m = require("./.sdk/model/sdk.json")
-  const t = (m.main && m.main.kit && m.main.kit.target) || {}
-  console.log(Object.keys(t).sort().join("\n"))
-')"
+# Each target generated in a folder of its own, and the one, if any, that
+# declares `output: root: true`.
+list_targets() {
+  node -e '
+    const m = require("./.sdk/model/sdk.json")
+    const t = (m.main && m.main.kit && m.main.kit.target) || {}
+    const root = "root" === process.argv[1]
+    console.log(Object.keys(t).sort().filter((n) =>
+      root === (true === (t[n] && t[n].output && t[n].output.root))).join("\n"))
+  ' "$1"
+}
+targets="$(list_targets folder)"
+atroot="$(list_targets root)"
 
 echo 'check-drift: deleting and regenerating every target ...'
 while IFS= read -r t; do
   [[ -n "$t" && -d "$t" ]] && rm -rf -- "$t"
 done <<< "$targets"
 
+# A target generated at the root owns the repository outside .sdk/, as the
+# others own their folders. Only tracked files go: what git ignores there,
+# such as installed dependencies, is not output.
+if [[ -n "$atroot" ]]; then
+  git ls-files -z -- . ':(exclude).sdk' | while IFS= read -r -d '' f; do
+    rm -f -- "$f"
+  done
+fi
+
 log="$(mktemp)"
 trap 'rm -f "$log"' EXIT
 if ! ( cd "$sdk_dir" && npm run generate ) >"$log" 2>&1; then

package/project/standard/.sdk/package.json

@@ -31,7 +31,7 @@
     "typescript": ">=6.0",
     "@voxgig/apidef": ">=8.17.0",
     "@voxgig/model": ">=12.0.0",
-    "@voxgig/sdkgen": ">=4.25.0",
+    "@voxgig/sdkgen": ">=4.30.0",
     "@voxgig/util": ">=0.5",
     "@voxgig/struct": ">=0.2",
     "jostraca": ">=0.39.0",

package/project/standard/.sdk/src/Root.ts

@@ -15,6 +15,8 @@ import {
   AgentGuide,
   Test,
 
+  SdkGenError,
+
 } from '@voxgig/sdkgen'
 
 import {
@@ -29,6 +31,7 @@ import { PointUtil, Content } from 'jostraca'
 
 import { Top } from './Top'
 import { BuildSDK } from './BuildSDK'
+import { rootPlan } from './RootPlan'
 
 
 const {
@@ -69,58 +72,79 @@ const Root = cmp(function Root(props: any) {
   ctx$.stdrep = {}
   names(ctx$.stdrep, model.Name, 'Project' + 'Name')
 
+  const plan = rootPlan(model.main[KIT], SdkGenError)
+
   Project({}, () => {
 
-    Top({})
+    if (plan.top) {
+      Top({})
+    }
 
-    BuildSDK({})
+    if (plan.build) {
+      BuildSDK({})
+    }
 
     each(target, (target: any) => {
+      const place = plan.place[target.name]
+
+      if (null == place) {
+        return
+      }
+
       names(target, target.name)
 
-      Folder({ name: target.name }, () => {
-
-        const phase = target.phase || {}
-        const phaseActive = (name: string): boolean =>
-          false !== (phase[name] && phase[name].active)
-
-        if (phaseActive('entity')) {
-          each(entity).filter((entity: any) => entity.active).map((entity: any) => {
-            names(entity, entity.name)
-            Entity({ target, entity })
-          })
-        }
-
-        if (phaseActive('feature')) {
-          each(feature).filter((feature: any) => feature.active).map((feature: any) => {
-            names(feature, feature.name)
-            Feature({ target, feature })
-          })
-        }
-
-        Main({ target })
-
-        if (phaseActive('readme')) {
-          Readme({ target })
-        }
-
-        // Per-target agent guides: <lang>/AGENTS.md + CLAUDE.md, and (driven
-        // internally by AgentGuide) a guide per active feature under
-        // <lang>/src/feature/<name>/. Placement mirrors Readme.
-        if (phaseActive('agentguide')) {
-          AgentGuide({ target })
-        }
-
-        if (phaseActive('test')) {
-          Test({ target })
-        }
-      })
+      if ('root' === place) {
+        targetPhases(target, entity, feature)
+      }
+      else {
+        Folder({ name: target.name }, () => {
+          targetPhases(target, entity, feature)
+        })
+      }
     })
 
   })
 })
 
 
+function targetPhases(target: any, entity: any, feature: any) {
+  const phase = target.phase || {}
+  const phaseActive = (name: string): boolean =>
+    false !== (phase[name] && phase[name].active)
+
+  if (phaseActive('entity')) {
+    each(entity).filter((entity: any) => entity.active).map((entity: any) => {
+      names(entity, entity.name)
+      Entity({ target, entity })
+    })
+  }
+
+  if (phaseActive('feature')) {
+    each(feature).filter((feature: any) => feature.active).map((feature: any) => {
+      names(feature, feature.name)
+      Feature({ target, feature })
+    })
+  }
+
+  Main({ target })
+
+  if (phaseActive('readme')) {
+    Readme({ target })
+  }
+
+  // Per-target agent guides: <lang>/AGENTS.md + CLAUDE.md, and (driven
+  // internally by AgentGuide) a guide per active feature under
+  // <lang>/src/feature/<name>/. Placement mirrors Readme.
+  if (phaseActive('agentguide')) {
+    AgentGuide({ target })
+  }
+
+  if (phaseActive('test')) {
+    Test({ target })
+  }
+}
+
+
 function makeFlow(def: any, data: any, stepMakers: Record<string, any>) {
 
   const steps: any = {}

package/project/standard/.sdk/src/RootPlan.ts

@@ -0,0 +1,64 @@
+
+// Import-free, so the scaffold's own tests can load it without the toolchain.
+
+
+type Place = 'folder' | 'root'
+
+
+type RootPlan = {
+  top: boolean
+  build: boolean
+
+  // Generated targets only: absent means not generated at all.
+  place: Record<string, Place>
+}
+
+
+type Fail = new (message: string) => Error
+
+
+function rootPlan(kit: any, Fail: Fail = Error): RootPlan {
+  const phase = kit?.phase || {}
+  const phaseActive = (name: string): boolean =>
+    false !== (phase[name] && phase[name].active)
+
+  const top = phaseActive('top')
+  const build = phaseActive('build')
+
+  const target = kit?.target || {}
+  const place: Record<string, Place> = {}
+
+  for (const name of Object.keys(target).sort()) {
+    if (null != target[name] && false !== target[name].active) {
+      place[name] = true === target[name].output?.root ? 'root' : 'folder'
+    }
+  }
+
+  const atRoot = Object.keys(place).filter((name: string) => 'root' === place[name])
+
+  if (1 < atRoot.length) {
+    throw new Fail(
+      'Only one target can be generated at the project root, and ' +
+      atRoot.length + ' declare `output: root: true`: ' + atRoot.join(', ') + '.')
+  }
+
+  if (1 === atRoot.length && top) {
+    throw new Fail(
+      'Target "' + atRoot[0] + '" is generated at the project root, where the ' +
+      'SDK repository files (README, LICENSE, Makefile, workflows) would ' +
+      'overwrite its own. Declare `main: kit: phase: top: active: false` in ' +
+      'model/project.aontu.')
+  }
+
+  return { top, build, place }
+}
+
+
+export type {
+  Place,
+  RootPlan,
+}
+
+export {
+  rootPlan,
+}