@voxgig/create-sdkgen 0.23.0 → 0.25.0

package/project/standard/.sdk/test/struct/select.aon

@@ -2,41 +2,39 @@
 basic: {
   set: [
     # Basic equality matching
-    { in: { query: {age:30}, obj: {a:{name:'Alice',age:30}, b:{name:'Bob',age:25}} }, 
+    { in: { query: {age:30}, obj: {a:{name:'Alice',age:30}, b:{name:'Bob',age:25}} },
       out: [{name:'Alice',age:30,'$KEY':'a'}] }
 
-      { in: { query: {name:'Bob'}, obj: {a:{name:'Alice',age:30}, b:{name:'Bob',age:25}} }, 
+      { in: { query: {name:'Bob'}, obj: {a:{name:'Alice',age:30}, b:{name:'Bob',age:25}} },
       out: [{name:'Bob',age:25,'$KEY':'b'}] }
-    
+
     # Multiple field equality
-    { in: { query: {age:30,city:'NYC'}, obj: {a:{age:30,city:'NYC'}, b:{age:30,city:'LA'}} }, 
+    { in: { query: {age:30,city:'NYC'}, obj: {a:{age:30,city:'NYC'}, b:{age:30,city:'LA'}} },
       out: [{age:30,city:'NYC','$KEY':'a'}] }
-    
-    # Array children
+
     { in: { query: {type:'user'},
-            obj: [{id:1,type:'user'}, {id:2,type:'admin'}, {id:3,type:'user'}] }, 
+            obj: [{id:1,type:'user'}, {id:2,type:'admin'}, {id:3,type:'user'}] },
       out: [{id:1,type:'user','$KEY':0}, {id:3,type:'user','$KEY':2}] }
-    
-    # No matches
-    { in: { query: {age:40}, obj: {a:{age:30}, b:{age:25}} }, 
+
+    { in: { query: {age:40}, obj: {a:{age:30}, b:{age:25}} },
       out: [] }
-    
+
     # Empty query matches all
-    { in: { query: {}, obj: {a:{x:1}, b:{x:2}} }, 
+    { in: { query: {}, obj: {a:{x:1}, b:{x:2}} },
       out: [{x:1,'$KEY':'a'}, {x:2,'$KEY':'b'}] }
-    
+
     # Non-object input
     { in: { query: {x:1}, obj: 'hello' }, out: [] }
     { in: { query: {x:1}, obj: 42 }, out: [] }
     { in: { query: {x:1}, obj: null }, out: [] }
     { in: { query: {x:1}, obj: undefined }, out: [] }
-    
+
     # Deep equality for objects
-    { in: { query: {data:{x:1,y:2}}, obj: {a:{data:{x:1,y:2}}, b:{data:{x:1,y:3}}} }, 
+    { in: { query: {data:{x:1,y:2}}, obj: {a:{data:{x:1,y:2}}, b:{data:{x:1,y:3}}} },
       out: [{data:{x:1,y:2},'$KEY':'a'}] }
-    
+
     # Deep equality for arrays
-    { in: { query: {tags:['a','b']}, obj: {a:{tags:['a','b']}, b:{tags:['a','c']}} }, 
+    { in: { query: {tags:['a','b']}, obj: {a:{tags:['a','b']}, b:{tags:['a','c']}} },
       out: [{tags:['a','b'],'$KEY':'a'}] }
   ]
 }
@@ -44,156 +42,141 @@ basic: {
 operators: {
   set: [
     # `$AND` operator
-    { in: { query: {'`$AND`':[{age:30}, {city:'NYC'}]}, 
-            obj: {a:{age:30,city:'NYC'}, b:{age:30,city:'LA'}, c:{age:25,city:'NYC'}} }, 
+    { in: { query: {'`$AND`':[{age:30}, {city:'NYC'}]},
+            obj: {a:{age:30,city:'NYC'}, b:{age:30,city:'LA'}, c:{age:25,city:'NYC'}} },
       out: [{age:30,city:'NYC','$KEY':'a'}] }
-    
+
     # `$AND` with no matches
-    { in: { query: {'`$AND`':[{age:30}, {city:'Boston'}]}, 
-            obj: {a:{age:30,city:'NYC'}, b:{age:30,city:'LA'}} }, 
+    { in: { query: {'`$AND`':[{age:30}, {city:'Boston'}]},
+            obj: {a:{age:30,city:'NYC'}, b:{age:30,city:'LA'}} },
       out: [] }
-    
-    # `$OR` operator
-    { in: { query: {'`$OR`':['x', 'y']}, 
-            obj: {a:'x', b:'z', c:'y'} }, 
+
+    { in: { query: {'`$OR`':['x', 'y']},
+            obj: {a:'x', b:'z', c:'y'} },
       out: ['x', 'y'] }
 
 
-    # TODO: review
-   
-    # { in: { query: {'$KEY':{'`$OR`':['b', 'c']}}, 
-    #         obj: {a:'x', b:'z', c:'y'} }, 
-    #   out: ['z', 'y'] }
 
-    # { in: { query: {'`$OR`':[{'$KEY':'b'}, {'$KEY':'c'}]}, 
-    #         obj: {a:'x', b:'z', c:'y'} }, 
-    #   out: ['z', 'y'] }
 
-      
-    { in: { query: {'`$OR`':[{age:25}, {age:35}]}, 
-            obj: {a:{age:30}, b:{age:25}, c:{age:35}} }, 
+
+
+    { in: { query: {'`$OR`':[{age:25}, {age:35}]},
+            obj: {a:{age:30}, b:{age:25}, c:{age:35}} },
       out: [{age:25,'$KEY':'b'}, {age:35,'$KEY':'c'}] }
-    
+
     # `$OR` with all matches
-    { in: { query: {'`$OR`':[{type:'user'}, {type:'admin'}]}, 
-            obj: [{type:'user'}, {type:'admin'}, {type:'guest'}] }, 
+    { in: { query: {'`$OR`':[{type:'user'}, {type:'admin'}]},
+            obj: [{type:'user'}, {type:'admin'}, {type:'guest'}] },
       out: [{type:'user','$KEY':0}, {type:'admin','$KEY':1}] }
-    
+
     # Nested `$AND` within `$OR`
-    { in: { query: {'`$OR`':[{'`$AND`':[{role:'user'}, {active:true}]}, {'`$AND`':[{role:'admin'}, {age:30}]}]}, 
-            obj: {a:{role:'admin',age:30,active:true}, b:{role:'user',age:25,active:true}, 
-                  c:{role:'user',age:30,active:false}, d:{role:'admin',age:30,active:false}} }, 
-      out: [{role:'admin',age:30,active:true,'$KEY':'a'}, {role:'user',age:25,active:true,'$KEY':'b'}, 
+    { in: { query: {'`$OR`':[{'`$AND`':[{role:'user'}, {active:true}]}, {'`$AND`':[{role:'admin'}, {age:30}]}]},
+            obj: {a:{role:'admin',age:30,active:true}, b:{role:'user',age:25,active:true},
+                  c:{role:'user',age:30,active:false}, d:{role:'admin',age:30,active:false}} },
+      out: [{role:'admin',age:30,active:true,'$KEY':'a'}, {role:'user',age:25,active:true,'$KEY':'b'},
             {role:'admin',age:30,active:false,'$KEY':'d'}] }
-    
+
     # Complex nested operators
-    { in: { query: {'`$AND`':[{'`$OR`':[{status:'active'}, {status:'pending'}]}, {priority:'high'}]}, 
-            obj: {a:{status:'active',priority:'high'}, b:{status:'active',priority:'low'}, 
-                  c:{status:'pending',priority:'high'}, d:{status:'done',priority:'high'}} }, 
+    { in: { query: {'`$AND`':[{'`$OR`':[{status:'active'}, {status:'pending'}]}, {priority:'high'}]},
+            obj: {a:{status:'active',priority:'high'}, b:{status:'active',priority:'low'},
+                  c:{status:'pending',priority:'high'}, d:{status:'done',priority:'high'}} },
       out: [{status:'active',priority:'high','$KEY':'a'}, {status:'pending',priority:'high','$KEY':'c'}] }
-    
+
     # Empty `$AND` array (should match all)
-    { in: { query: {'`$AND`':[]}, obj: {a:{x:1}, b:{x:2}} }, 
+    { in: { query: {'`$AND`':[]}, obj: {a:{x:1}, b:{x:2}} },
       out: [{x:1,'$KEY':'a'}, {x:2,'$KEY':'b'}] }
-    
+
     # Empty `$OR` array (should match none)
-    { in: { query: {'`$OR`':[]}, obj: {a:{x:1}, b:{x:2}} }, 
+    { in: { query: {'`$OR`':[]}, obj: {a:{x:1}, b:{x:2}} },
       out: [] }
 
 
-    { in: { query: {a:{'`$GT`':10}}, obj: [{a:9},{a:10},{a:11},{a:12}] }, 
+    { in: { query: {a:{'`$GT`':10}}, obj: [{a:9},{a:10},{a:11},{a:12}] },
       out: [{a:11,'$KEY':2},{a:12,'$KEY':3}] }
 
-    { in: { query: {a:{'`$GTE`':10}}, obj: [{a:9},{a:10},{a:11},{a:12}] }, 
+    { in: { query: {a:{'`$GTE`':10}}, obj: [{a:9},{a:10},{a:11},{a:12}] },
       out: [{a:10,'$KEY':1},{a:11,'$KEY':2},{a:12,'$KEY':3}] }
 
-      
-    { in: { query: {b:{'`$LT`':10}}, obj: [{b:9},{b:10},{b:11},{b:12}] }, 
+
+    { in: { query: {b:{'`$LT`':10}}, obj: [{b:9},{b:10},{b:11},{b:12}] },
       out: [{b:9,'$KEY':0}] }
 
-    { in: { query: {b:{'`$LTE`':10}}, obj: [{b:9},{b:10},{b:11},{b:12}] }, 
+    { in: { query: {b:{'`$LTE`':10}}, obj: [{b:9},{b:10},{b:11},{b:12}] },
       out: [{b:9,'$KEY':0},{b:10,'$KEY':1}] }
 
-      
-    { in: { query: {a:b:'`$LT`':10}, obj: [{a:b:9},{a:b:10},{a:b:11},{a:b:12}] }, 
+
+    { in: { query: {a:b:'`$LT`':10}, obj: [{a:b:9},{a:b:10},{a:b:11},{a:b:12}] },
       out: [{a:b:9,'$KEY':0}] }
 
-           
-    { in: { query: {x:{y:20}}, obj: [{x:{y:20,z:220}},{x:{y:21,z:221}}] }, 
+
+    { in: { query: {x:{y:20}}, obj: [{x:{y:20,z:220}},{x:{y:21,z:221}}] },
       out: [{x:{y:20,z:220},'$KEY':0}] }
 
-    { in: { query: {s0:'`$LIKE`':'[aA][bB][cC]'}, obj: [{s0:'DEf'},{s0:'ABc'}] }, 
+    { in: { query: {s0:'`$LIKE`':'[aA][bB][cC]'}, obj: [{s0:'DEf'},{s0:'ABc'}] },
       out: [{s0:'ABc','$KEY':1}] }
 
 
-    { in: { query: {'`$NOT`':10}, obj: [9,10,11] }, 
+    { in: { query: {'`$NOT`':10}, obj: [9,10,11] },
       out: [9,11] }
 
-    { in: { query: {'`$NOT`':{n0:'x'}}, obj: [{n0:x},{n0:y},{n0:z}] }, 
+    { in: { query: {'`$NOT`':{n0:'x'}}, obj: [{n0:x},{n0:y},{n0:z}] },
       out: [{n0:y,'$KEY':1},{n0:z,'$KEY':2}] }
 
     { in: { query: {'`$NOT`':{'`$OR`':[{x:1},{y:2}]}},
-            obj: [{x:1,y:3},{x:2,y:2},{x:3,y:1}] }, 
+            obj: [{x:1,y:3},{x:2,y:2},{x:3,y:1}] },
       out: [{x:3,y:1,'$KEY':2}] }
-      
+
   ]
 }
 
 edge: {
   set: [
     # Mixed equality and operators
-    { in: { query: {type:'user', '`$OR`':[{status:'active'}, {admin:true}]}, 
-            obj: [{type:'user',status:'active'}, {type:'user',status:'inactive',admin:true}, 
-                  {type:'guest',status:'active'}] }, 
+    { in: { query: {type:'user', '`$OR`':[{status:'active'}, {admin:true}]},
+            obj: [{type:'user',status:'active'}, {type:'user',status:'inactive',admin:true},
+                  {type:'guest',status:'active'}] },
       out: [{type:'user',status:'active','$KEY':0}, {type:'user',status:'inactive',admin:true,'$KEY':1}] }
-    
-    
-    { in: { query: {value:q}, obj: {a:{value:q}, b:{value:p},c:{}} }, 
+
+
+    { in: { query: {value:q}, obj: {a:{value:q}, b:{value:p},c:{}} },
       out: [{value:q,'$KEY':'a'}] }
 
-    { in: { query: {value:null}, obj: {a:{value:null}, b:{value:0}, c:{}} }, 
+    { in: { query: {value:null}, obj: {a:{value:null}, b:{value:0}, c:{}} },
       out: [{value:null,'$KEY':'a'}] }
-    
-    { in: { query: {active:true}, obj: {a:{active:true}, b:{active:false}, c:{active:1}} }, 
+
+    { in: { query: {active:true}, obj: {a:{active:true}, b:{active:false}, c:{active:1}} },
       out: [{active:true,'$KEY':'a'}] }
-    
+
     # Number comparison (exact match)
-    { in: { query: {count:0}, obj: {a:{count:0}, b:{count:false}, c:{count:'0'}} }, 
+    { in: { query: {count:0}, obj: {a:{count:0}, b:{count:false}, c:{count:'0'}} },
       out: [{count:0,'$KEY':'a'}] }
 
-      
-    { in: { query: {'`$OR`':[{a:1},{a:2}]}, obj: [{a:0}, {a:1}, {a:2}, {a:3}] }, 
+
+    { in: { query: {'`$OR`':[{a:1},{a:2}]}, obj: [{a:0}, {a:1}, {a:2}, {a:3}] },
       out: [{a:1,'$KEY':1}, {a:2,'$KEY':2}] }
 
-    { in: { query: {a:{'`$OR`':[10,20]}}, obj: [{a:0}, {a:10}, {a:20}, {a:30}] }, 
+    { in: { query: {a:{'`$OR`':[10,20]}}, obj: [{a:0}, {a:10}, {a:20}, {a:30}] },
       out: [{a:10,'$KEY':1}, {a:20,'$KEY':2}] }
 
     { in: { query: {a2:{'`$OR`':[{b2:1},{b2:2}]}},
-            obj: [{a2:{b2:0}}, {a2:{b2:1}}, {a2:{b2:2}}, {a2:{b2:3}}] }, 
+            obj: [{a2:{b2:0}}, {a2:{b2:1}}, {a2:{b2:2}}, {a2:{b2:3}}] },
       out: [{a2:{b2:1},'$KEY':1}, {a2:{b2:2},'$KEY':2}] }
 
-    { in: { query: {'`$OR`':[{a3:{'`$OR`':[1]}}]}, obj: [{a3:0}, {a3:1}, {a3:2}] }, 
+    { in: { query: {'`$OR`':[{a3:{'`$OR`':[1]}}]}, obj: [{a3:0}, {a3:1}, {a3:2}] },
       out: [{a3:1,'$KEY':1}] }
 
 
     { in: { query: {c0:{'`$AND`':[{x:1},{y:2}]}},
-            obj: [{c0:{x:1,y:3,z:0}}, {c0:{x:1,y:2,z:1}}] }, 
+            obj: [{c0:{x:1,y:3,z:0}}, {c0:{x:1,y:2,z:1}}] },
       out: [{c0:{x:1,y:2,z:1},'$KEY':1}] }
 
     { in: { query: {c0:{'`$AND`':[{x:1},{y:{'`$OR`':[2,3]}}]}},
-            obj: [{c0:{x:1,y:3,z:0}}, {c0:{x:1,y:2,z:1}}, {c0:{x:1,y:1,z:2}}] }, 
-      out: [{c0:{x:1,y:3,z:0},'$KEY':0}, {c0:{x:1,y:2,z:1},'$KEY':1}] }     
+            obj: [{c0:{x:1,y:3,z:0}}, {c0:{x:1,y:2,z:1}}, {c0:{x:1,y:1,z:2}}] },
+      out: [{c0:{x:1,y:3,z:0},'$KEY':0}, {c0:{x:1,y:2,z:1},'$KEY':1}] }
   ]
 }
 
 
-# path alternates selection
-# NOTES FOR SDK:
-#  build query by union of all select keys, getting values from operation spec, match
-#  need a deterministic sort of alts so multiple selects (should not happen) have at least
-#    a stable list of returned alts order. also $path as get out of jail
-#      normalize: /a/{x}/b/ -> path$:'/a/{}/b'
-#  if no alt found, use select to indicate missing select options
 alts: {
   data: obj0: [
     { select:foo_id:true, x:1 }
@@ -211,7 +194,7 @@ alts: {
     { select:{'$action':foo,zed_id:true}, x:31 }
     { select:{'$action':bar,zed_id:true}, x:32 }
   ]
-  
+
   set: [
     { in: { query: select: {
               foo_id:true  # boolean true means value exists (incl. JSON null)
@@ -236,12 +219,12 @@ alts: {
              obj: $.struct.select.alts.data.obj2 }
        out: [{ '$KEY': 0, select: { query:q0:v0 }, x: 21} ]
      }
-     
+
      { in: { query: select: { '$action':bar, zed_id:true }
              obj: $.struct.select.alts.data.obj3 }
        out: [{ '$KEY': 1, select: {'$action':bar,zed_id:true}, x: 32} ]
      }
-     
+
 
   ]
 }

package/src/create-sdkgen.ts

@@ -45,8 +45,6 @@ const { names, Jostraca } = JostracaModule
 const SDK_FOLDER = '.sdk'
 
 
-// TODO: CreateSdkGen opts and generate opts should be mostly the same, and
-// generate should override
 function CreateSdkGen(opts: FullCreateSdkGenOptions) {
   const fs = opts.fs || Fs
 
@@ -107,12 +105,6 @@ function CreateSdkGen(opts: FullCreateSdkGenOptions) {
       folder,
       log: log.child({ cmp: 'jostraca' }),
       meta: { spec },
-      // Overwrite the scaffolded project (.sdk components, templates, build
-      // config) rather than 3-way merge. The scaffold is toolchain-derived and
-      // not hand-edited; merging against a drifting .jostraca base keeps STALE
-      // components/templates on a toolchain bump (so a fix never propagates) and
-      // can inject <<<<<<< markers. See @voxgig/sdkgen
-      // docs/explanation/regeneration-overwrite.md.
       existing: {
         txt: {
           write: true,
@@ -166,7 +158,6 @@ function CreateSdkGen(opts: FullCreateSdkGenOptions) {
 
     projectFolder = Path.resolve(Path.join(__dirname, 'project', spec.project))
 
-    // TODO: support auto install project npm package (specific version) in a special cache folder
 
     if (!fs.existsSync(projectFolder)) {
       projectFolder = spec.project
@@ -275,17 +266,6 @@ async function installNpm(spec: GenerateSpec, opts: any, model: any) {
     await runNpm(['install'], spawn_opts)
   }
 
-  // `-t` / `-f` are INDEPENDENT of `--no-install`: the documented contract is
-  // that --no-install skips `npm install`, not that it drops the requested
-  // targets and features. Adding them is still valid without an install when
-  // the project already has its toolchain (re-scaffolding an existing folder
-  // is a supported flow — "if run against an existing folder generated files
-  // will be overwritten").
-  //
-  // They ARE npm run scripts that resolve @voxgig/sdkgen from node_modules, so
-  // without one they cannot work. Fail with an actionable message rather than
-  // the raw module-resolution error — and rather than silently skipping, which
-  // reports success while leaving config.aon without the requested entries.
   const wanted = [
     (spec.target ?? []).length ? '--target' : '',
     (spec.feature ?? []).length ? '--feature' : '',
@@ -342,21 +322,6 @@ async function installFeatures(spec: GenerateSpec, opts: any, model: any, spawn_
 }
 
 
-/*
-function logfiles(info: any, log: ReturnType<typeof Pino>) {
-  const cwd = process.cwd()
-
-    ; Object.keys(info.files).map(action => {
-      let entries = info.files[action]
-      if (0 < entries.length) {
-        log.debug({
-          point: 'file-' + action, entries,
-          note: '\n' + entries.map((n: any) => n.replace(cwd, '.')).join('\n')
-        })
-      }
-    })
-}
-*/
 
 export type {
   CreateSdkGenOptions,

package/src/project/standard/CreateRoot.ts

@@ -1,7 +1,6 @@
 
 
 import Path from 'node:path'
-// import * as Fs from 'node:fs'
 
 import {
   names,
@@ -62,39 +61,6 @@ log/
 `
 
 
-// The guide overlay is the ONE model file the user owns.
-//
-// Everything else the scaffold writes is toolchain-derived and is deliberately
-// OVERWRITTEN (see the `existing.txt.write` rationale in create-sdkgen.ts) so a
-// toolchain fix propagates. `model/guide/guide.aon` is the exception: apidef
-// unifies it OVER the heuristic classification, and it is where every
-// documented customization lives — entity rename, hide, move, activate,
-// per-path deactivation, method override, param rename, response transform.
-// Copying the stub over it destroyed that work on every re-scaffold, and
-// cedar-regen.sh re-scaffolds on every regen, so the loss was silent and
-// repeated.
-//
-// It is excluded from the bulk Copy and merged instead (see mergeGuide).
-// The PROJECT overlay: the second model file the user owns.
-//
-// `guide.aon` owns what the API looks like. This owns what the PROJECT is —
-// publication values above all. The sdkgen schema tells you to declare those
-// in `model/sdk.aon` "where they survive a resync", and that was simply not
-// true: ModelSdk rewrites sdk.aon from its template on every scaffold, so a
-// version or package name declared there vanished before the model was built,
-// with no error. The cedar fleet ran for months with every manifest pinned at
-// the schema default 0.0.1 while its git tags climbed past 0.1.1, and this is
-// why.
-//
-// sdk.aon cannot simply be merged the way guide.aon is. Its template owns
-// `name`, `origin` and especially `def` — the OpenAPI filename, which really
-// does change (three cedar specs were renamed in one week). A "keep the user's
-// file" merge would freeze `def` at a spec that no longer exists and break
-// regeneration. So the template keeps sole ownership of sdk.aon, and the
-// user gets a file of their own that sdk.aon includes.
-//
-// Written ONCE. If it exists, it is re-emitted byte-for-byte, so a
-// re-scaffold is a no-op on it.
 const PROJECT_FILE = 'project.aon'
 const PROJECT_STUB = `# Project overlay — YOURS. The scaffold creates this file once and never
 # overwrites it, unlike every other file it writes.
@@ -127,17 +93,6 @@ const GUIDE_FILE = 'guide.aon'
 const GUIDE_REL = ['model', 'guide', GUIDE_FILE]
 
 
-// Rename a user-owned overlay from its pre-2026-08 `.aontu` name to `.aon`.
-//
-// Both overlays are read-if-present and written-if-absent, which is exactly
-// the shape that turns an extension rename into DATA LOSS rather than a
-// rename: look for `guide.aon`, find nothing, write a fresh template over the
-// top, and the user's entity renames, hides and overrides are still sitting
-// in `guide.aontu` being ignored. 660 generated repos carry one.
-//
-// So the legacy file is moved to the new name BEFORE anything reads or writes
-// it. Contents are untouched; only the name changes. Idempotent — once the
-// `.aon` exists this does nothing, so a re-scaffold stays a no-op.
 function migrateOverlay(fs: any, dir: string, name: string): void {
   const next = Path.join(dir, name + '.aon')
   const prev = Path.join(dir, name + '.aontu')
@@ -145,15 +100,6 @@ function migrateOverlay(fs: any, dir: string, name: string): void {
     return
   }
   try {
-    // RENAME THE FILE *AND* ITS INCLUDES. An overlay written before the
-    // rename includes the toolchain schemas by their old names —
-    // `@"@voxgig/apidef/model/guide.aontu"` — and apidef 8 no longer ships
-    // that file, so a migration that moved the file but kept its contents
-    // verbatim produced a project that could not resolve its own guide.
-    // mergeGuide cannot repair this either: it keeps the user's lines and
-    // only ADDS missing template includes, so the dead one would survive
-    // beside the new one. Only `@`-include extensions are touched; nothing
-    // else in the user's file is rewritten.
     const src = String(fs.readFileSync(prev))
       .replace(/(@['"][^'"]+)\.aontu(['"])/g, '$1.aon$2')
     fs.writeFileSync(next, src)
@@ -166,17 +112,6 @@ function migrateOverlay(fs: any, dir: string, name: string): void {
 }
 
 
-// Merge the guide template into an existing guide overlay.
-//
-// A guide is the template's `@`-includes plus whatever the user added. The
-// includes are the only part the template OWNS, so the merge is: keep the
-// user's file verbatim, and restore any include it is missing. When nothing
-// is missing — the normal case — the file is returned byte-identical, so a
-// re-scaffold is a no-op on it.
-//
-// Missing includes are restored at the TOP, not appended: `base-guide.aon`
-// carries the heuristic classification that the user's overrides unify over,
-// and the overlay reads correctly only when the includes precede it.
 function mergeGuide(existing: string | null, template: string): string {
   if (null == existing) {
     return template
@@ -184,18 +119,6 @@ function mergeGuide(existing: string | null, template: string): string {
 
   const isInclude = (line: string) => line.trim().startsWith('@')
 
-  // AN INCLUDE IS THE FILE IT NAMES, whichever way the `./` falls.
-  //
-  // The template gained a `./` when aontu 0.65 made a bare single-segment
-  // include name a PACKAGE (ADR-039). Every guide written before that says
-  // `@"base-guide.aon"`, and `guide.aon` is project-owned: the scaffold
-  // writes it once and never again, so those files stay as they are until
-  // something migrates them.
-  //
-  // Comparing the raw lines read the old spelling as a DIFFERENT include, so
-  // a re-scaffold restored one the file already had — leaving the guide
-  // including `base-guide.aon` twice, under two spellings, which is the one
-  // thing this merge exists to avoid.
   const key = (line: string) => line.trim().replace(/^@"\.\//, '@"')
 
   const have = new Set(existing.split('\n').map(key))
@@ -212,26 +135,10 @@ function mergeGuide(existing: string | null, template: string): string {
 }
 
 
-// The OpenAPI filename is inherited from the upstream API slug, and upstream
-// slugs are not constrained: the freepublicapis corpus contains apostrophes
-// (catherine-shulman's-quotes), accents (dólar-y-monedas, kölner-adressen),
-// and '!' / '>' / '_'. That name is copied into .sdk/def/ AND written verbatim
-// into a single-quoted aontu string in sdk.aon:
-//
-//     def: 'catherine-shulman's-quotes_0.1.0.json'
-//                              ^ terminates the string -> AontuError, no SDK
-//
-// Slugs are [a-z0-9-]; a filename additionally needs '.' and '_' for the
-// version segment and extension, so those are kept — which also means every
-// already-conforming name (including cedar's dotted gitlab-v4-swagger-2.0.yaml)
-// is untouched and no repo churns. Everything else is folded to '-'.
 function sanitizeDefName(filename: string): string {
   const clean = filename
-    .normalize('NFKD').replace(/[\u0300-\u036f]/g, '')  // dólar -> dolar
+    .normalize('NFKD').replace(/[\u0300-\u036f]/g, '')
     .toLowerCase()
-    // Quotes are ELIDED, not folded to '-', so the filename agrees with the
-    // repo name apidef's sanitizeSlug derives from the same slug:
-    // catherine-shulman's-quotes -> catherine-shulmans-quotes(-sdk).
     .replace(/['’"]/g, '')
     .replace(/[^a-z0-9._-]+/g, '-')
     .replace(/-+/g, '-')
@@ -244,17 +151,13 @@ function sanitizeDefName(filename: string): string {
 }
 
 
-// TODO: rename to RootSdk
 const CreateRoot = cmp(function CreateRoot(props: any) {
   const { ctx$, ctx$: { folder }, spec, model } = props
   const fs = ctx$.fs()
 
-  // TODO: move to @voxgig/util as duplicated
   model.const = { name: model.name }
   names(model.const, model.name)
   model.const.year = new Date().getFullYear()
-  // Scaffold is MIT-licensed (matches the emitted LICENSE and tm/LICENSE);
-  // set directly rather than via names() so the value stays 'MIT', not 'Mit'.
   model.const.License = 'MIT'
 
   ctx$.model = model
@@ -263,11 +166,7 @@ const CreateRoot = cmp(function CreateRoot(props: any) {
     const from =
       Path.resolve(Path.join(__dirname, '..', '..', '..', 'project', 'standard'))
 
-    // console.log('FROM', from)
 
-    // Copy `exclude` matches the SOURCE-RELATIVE path exactly, so this names
-    // the one guide under the scaffold and nothing else. It is re-emitted,
-    // merged, in the model folder below.
     const guideExclude = [spec.sdk_folder, ...GUIDE_REL].join('/')
 
     Copy({
@@ -296,7 +195,6 @@ const CreateRoot = cmp(function CreateRoot(props: any) {
       })
 
       Folder({ name: 'def' }, () => {
-        // TODO: file existence check should be jostraca util
         if (fs.existsSync(origdef)) {
           Copy({ from: origdef, to: projdef })
         }