@voxgig/create-sdkgen 0.28.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/create-sdkgen",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "main": "dist/create-sdkgen.js",
   "type": "commonjs",
   "types": "dist/create-sdkgen.d.ts",

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.

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/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,
+}