enablement-build-template-generate 1.0.20 → 1.3.0

package/README.md

@@ -12,11 +12,13 @@ npx enablement-build-template-generate@latest [flags]
 
 ## How it works
 
-1. **Detect platform** — Checks for `manifest.json` (preferred) or `templated.json` (legacy) in `.cicd/` (ADO) or `.github/` (GitHub). Defaults to `ado` if none are found, or use `--platform` to override.
-2. **Read config** — If `manifest.json` is present, reads the `templated` section (each package maps to its own job template file). If only `templated.json` is present, reads the legacy `{ rootPath, template }` format and globs for packages automatically.
-3. **Expand job templates** — For each package, reads its job snippet template and fills in placeholders. When using `manifest.json`, metadata (`folderName`, `packageFolder`) comes from `manifest.cicd`; when using `templated.json`, package names are read from each folder's manifest file.
-4. **Stitch** — Joins all expanded job snippets and substitutes them into the document template at the named placeholder.
-5. **Write output** — Writes the final file one level above the template directory (`.github/templates/` → `.github/` or `.cicd/templates/` → `.cicd/`), wrapped in `DO NOT EDIT` banners.
+1. **Select platform** — Uses Azure DevOps (`.cicd/`) by default. Pass `--platform github` to use GitHub (`.github/`).
+2. **Read config** — `{configDir}/templates/templated.json` is the source of truth. If `manifest.json` still has a `templated` section (from older tooling), it's read once, merged into `templated.json`, and removed from `manifest.json`. A `templated.json` in the legacy `{ rootPath, template }` shape is converted to the current format (packages discovered by globbing `rootPath`).
+3. **Detect new packages** — Any package not yet assigned a template (scanned via `--children`/auto-detected workspace roots) is classified by type (node/python/dotnet/docker) and assigned a template, reusing the convention of other packages in the same folder or of the same type where possible.
+4. **Persist** — `templated.json` (and `manifest.json`, if it needed migrating) is written back, only when something actually changed.
+5. **Expand job templates** — For each package, reads its job snippet template and fills in placeholders (`folderName`/`packageFolder`/`metadata` come from `templated.json`'s own `cicd` section). Packages are ordered so that, per `manifest.json`'s `dependencies` graph (when present), a package's local dependencies are generated before it, as much as possible.
+6. **Stitch** — Joins all expanded job snippets and substitutes them into the document template at the named placeholder.
+7. **Write output** — Writes the final file one level above the template directory (`.github/templates/` → `.github/` or `.cicd/templates/` → `.cicd/`), wrapped in `DO NOT EDIT` banners.
 
 ---
 
@@ -24,22 +26,22 @@ npx enablement-build-template-generate@latest [flags]
 
 | Flag | Default | Description |
 |---|---|---|
-| `--platform <name>` | auto-detect | Force the platform: `ado` (Azure DevOps) or `github` (GitHub Actions). Auto-detected from `manifest.json` or `templated.json` presence in `.cicd/` or `.github/`. |
-| `--exclude <list>` | — | Comma- or space-separated list of package folder names to skip during generation. |
+| `--platform <name>` | `ado` | Select the platform: `ado` (Azure DevOps) or `github` (GitHub Actions). |
+| `--children <dirs>` | auto-detect | Comma- or space-separated list of top-level directories to scan when detecting new (not-yet-configured) packages. When omitted, directories are read from `pnpm-workspace.yaml` or `package.json` workspaces automatically. |
+| `--exclude <list>` | — | Comma- or space-separated list of names to skip: package folder names during generation, and top-level directories (from `--children` or auto-detection) during new-package scanning. |
 | `--debug` | off | Print verbose output. |
 
 ---
 
 ## Config source
 
-The generator supports two config formats, checked in this order:
+### `templated.json` (current format)
 
-### 1. `manifest.json` (preferred)
-
-Reads the `templated` section of `{configDir}/manifest.json` (produced by `enablement-build-manifest`). Each key is the **output filename**; each value maps a placeholder variable name to a per-package template mapping.
+`{configDir}/templates/templated.json` is the source of truth for template routing. Each key under `templated` is the **output filename**; each value maps a placeholder variable name to a per-package template mapping. `cicd` carries the per-package metadata generation needs.
 
 ```json
 {
+  "version": 2,
   "templated": {
     "build.yml": {
       "PACKAGES": {
@@ -48,30 +50,24 @@ Reads the `templated` section of `{configDir}/manifest.json` (produced by `enabl
         "my-scope/python-lib":  ["build_python_package.yml", "build_scan.yml"]
       }
     }
+  },
+  "cicd": {
+    "my-scope/component-a": { "folderName": "component-a", "packageFolder": "packages" }
   }
 }
 ```
 
 Each package name maps to a **single template filename** or an **array of template filenames** (all expanded in order for that package). Template lookup tries the active platform templates directory first (`.cicd/templates/` or `.github/templates/`) and then falls back to the other platform directory if a file is missing.
 
-Package metadata (`folderName`, `packageFolder`) is read from `manifest.cicd[packageName]` and used to fill template placeholders.
+Package metadata (`folderName`, `packageFolder`, `metadata`) is read from `templated.json`'s own `cicd` map and used to fill template placeholders.
 
-### 2. `templated.json` (legacy fallback)
+A `templated.json` in the legacy `{ rootPath, template }` shape (no top-level `templated`/`version` key) is converted to the current format automatically — packages are discovered by globbing `rootPath` for `package.json`/`version.json`/`pyproject.toml`, and the result is written back.
 
-When `manifest.json` is absent, reads `{configDir}/templates/templated.json`. Each entry provides a `rootPath` to glob for packages and a single `template` applied to all discovered packages. Template lookup still uses active-platform-first, then falls back to the other platform templates folder if needed.
+### `manifest.json` (one-time migration source + dependency graph)
 
-```json
-{
-  "build.yml": {
-    "PACKAGES": {
-      "rootPath": "../../packages",
-      "template": "build_node_component.yml"
-    }
-  }
-}
-```
+If `{configDir}/manifest.json` still has a `templated` section (from older tooling, or `enablement-build-manifest` before it stopped writing one), it's merged into `templated.json` and removed from `manifest.json` — existing assignments in `templated.json` win over stale ones from `manifest.json`.
 
-Package names are read from each folder's `package.json`, `version.json`, or `pyproject.toml`.
+Independently of that migration, when `manifest.json` exists its `dependencies` map (`{ "<package>": ["<local-dep>", ...] }`) is used to order generation: within each placeholder, a package's local dependencies are generated before it, as much as possible (dependencies outside that placeholder's package list, or on a package that also depends back on it, are simply skipped rather than causing an error).
 
 ---
 
@@ -101,9 +97,9 @@ Each job snippet template is expanded once per package. The following placeholde
 | `{full}` | Full npm package name including scope (e.g. `@scope/my-component`) |
 | `{path}` | The package folder root (from `cicd[pkg].packageFolder`, e.g. `packages`) |
 | `{other}` | Expands to a comma-separated list of paths to every **other** package in the same variable — useful for pipeline dependency declarations |
-| `{metadataKey}` | Custom placeholders like `{owner}` or `{tier}` are replaced from `manifest.cicd[packageName].metadata` (**manifest.json mode only**) |
+| `{metadataKey}` | Custom placeholders like `{owner}` or `{tier}` are replaced from `templated.json`'s `cicd[packageName].metadata` |
 
-In `templated.json` legacy mode, custom metadata placeholders are not supported and remain unchanged in output.
+Custom metadata placeholders aren't supported for a package still being discovered via the legacy `{ rootPath, template }` conversion (they remain unchanged in output) — once converted, `templated.json`'s `cicd` map can carry `metadata` for any package.
 
 ---
 
@@ -111,25 +107,25 @@ In `templated.json` legacy mode, custom metadata placeholders are not supported
 
 Job template files live in the templates subfolder; document templates and generated output files are one level up.
 
-**Azure DevOps** (when `.cicd/manifest.json` exists):
+**Azure DevOps**:
 ```
 .cicd/
-├── manifest.json          ← source of truth for templated config (preferred)
+├── manifest.json          ← optional: dependency graph for ordering, one-time templated migration source
 ├── build.yml              ← generated output
 └── templates/
     ├── build.yml          ← document template
-    ├── templated.json     ← legacy config (used when manifest.json is absent)
+    ├── templated.json     ← source of truth for templated config
     └── build_node_component.yml  ← job snippet template
 ```
 
-**GitHub Actions** (when `.github/manifest.json` exists):
+**GitHub Actions**:
 ```
 .github/
-├── manifest.json          ← source of truth for templated config (preferred)
+├── manifest.json          ← optional: dependency graph for ordering, one-time templated migration source
 ├── build.yml              ← generated output
 └── templates/
     ├── build.yml          ← document template
-    ├── templated.json     ← legacy config (used when manifest.json is absent)
+    ├── templated.json     ← source of truth for templated config
     └── build_node_component.yml  ← job snippet template
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "enablement-build-template-generate",
-  "version": "1.0.20",
+  "version": "1.3.0",
   "description": "Generates build yaml for mono repos",
   "type": "module",
   "module": "./src/index.mjs",
@@ -8,16 +8,12 @@
   "bin": "./src/index.mjs",
   "dependencies": {
     "globby": "^16.2.0",
-    "user": "^0.0.0"
+    "user": "^0.0.0",
+    "enablement-build-manifest": "1.4.0"
   },
   "devDependencies": {
     "jest": "^30.4.2"
   },
-  "scripts": {
-    "start": "node src/index.mjs",
-    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
-    "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch"
-  },
   "jest": {
     "testEnvironment": "node",
     "testMatch": [
@@ -25,5 +21,10 @@
     ]
   },
   "license": "MIT",
-  "author": "Contributors"
+  "author": "Contributors",
+  "scripts": {
+    "start": "node src/index.mjs",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch"
+  }
 }

package/src/index.mjs

@@ -15,6 +15,17 @@ import {
   resolveOtherPlaceholders,
   applyVarsToDocTemplate,
   wrapWithBanner,
+  resolveWorkspaceChildren,
+  excludeChildren,
+  buildPackageJsonGlob,
+  detectCicdType,
+  isAdvancedTemplatedFormat,
+  TEMPLATED_JSON_ADVANCED_VERSION,
+  extractGenerationCicd,
+  collectAssignedPackages,
+  listBuildTemplateFiles,
+  chooseAssignmentForNewPackage,
+  topologicalSort,
 } from './lib.mjs';
 
 const __dirname = url.fileURLToPath(new URL('.', import.meta.url));
@@ -67,14 +78,17 @@ function resolveFolderName(pkgName, info = {}) {
 // ---------------------------------------------------------------------------
 // Expand using manifest.json "templated" section (new format)
 // ---------------------------------------------------------------------------
-function expandVarFromManifest(varname, packageMap, cicd, templatePath, fallbackTemplatePath, options) {
+function expandVarFromManifest(varname, packageMap, cicd, templatePath, fallbackTemplatePath, options, dependencies = {}) {
   return new Promise((resolve, reject) => {
     try {
-      const packageNames = Object.keys(packageMap).filter(pkg => {
+      const filteredNames = Object.keys(packageMap).filter(pkg => {
         if (packageMap[pkg] === false) return false;
         const folderName = resolveFolderName(pkg, cicd[pkg] || {});
         return !options.exclude.includes(folderName);
       });
+      // Order so a package's local dependencies are generated before it,
+      // as much as possible (per manifest.json's "dependencies").
+      const packageNames = topologicalSort(filteredNames, dependencies);
 
       const allFolderNames = packageNames.map(pkg => resolveFolderName(pkg, cicd[pkg] || {}));
 
@@ -113,86 +127,198 @@ function expandVarFromManifest(varname, packageMap, cicd, templatePath, fallback
 }
 
 // ---------------------------------------------------------------------------
-// Expand using templated.json (legacy format: rootPath + template glob)
+// Convert one legacy templated.json entry ({ rootPath, template }) into the
+// advanced format: discover the packages currently under rootPath and assign
+// each of them the entry's template, recording their folder/packageFolder.
 // ---------------------------------------------------------------------------
-function expandVarFromTemplatedJson(varname, jobConfig, templatePath, fallbackTemplatePath, options) {
-  return new Promise((resolve, reject) => {
-    const jobTemplate = readJobTemplate(jobConfig.template, templatePath, fallbackTemplatePath);
-    const cwd = path.join(templatePath, jobConfig.rootPath);
-    const search = buildSearchGlobs(options.exclude);
-
-    globby(search, { cwd }).then((files) => {
-      const folderBest = groupByFolder(files);
-      const allNames = Object.keys(folderBest).sort().filter(n => !options.exclude.includes(n));
-
-      const expandedJobs = allNames.map(name => {
-        const content = readFileSync(path.join(cwd, folderBest[name].filePath), 'utf8');
-        const ext = path.extname(folderBest[name].filePath).substring(1).toLowerCase();
-        const fullName = parseManifestName(content, ext) || name;
-        const safe = makeSafe(name);
-        const packageName = resolvePackageName(fullName);
-        const jobRoot = path.relative(process.cwd(), cwd);
-        return expandJobTemplate(jobTemplate, { name, safe, packageName, fullName, jobRoot, metadata: {} });
-      });
+async function convertLegacyEntry(jobConfig, templatePath, options) {
+  const cwd = path.join(templatePath, jobConfig.rootPath);
+  const search = buildSearchGlobs(options.exclude);
+  const files = await globby(search, { cwd });
+
+  const folderBest = groupByFolder(files);
+  const allNames = Object.keys(folderBest).sort().filter(n => !options.exclude.includes(n));
+  const packageFolder = path.relative(process.cwd(), cwd);
+
+  const pkgMap = {};
+  const cicdEntries = {};
+  allNames.forEach(name => {
+    const content = readFileSync(path.join(cwd, folderBest[name].filePath), 'utf8');
+    const ext = path.extname(folderBest[name].filePath).substring(1).toLowerCase();
+    const fullName = parseManifestName(content, ext) || name;
+    pkgMap[fullName] = jobConfig.template;
+    cicdEntries[fullName] = { folderName: name, packageFolder };
+  });
 
-      const jobs = resolveOtherPlaceholders(expandedJobs.join('\n'), allNames, cwd);
-      resolve({ name: varname, text: jobs });
-    }, reject);
+  return { pkgMap, cicdEntries };
+}
+
+// Convert a whole legacy-format templated.json document into the advanced
+// { templated, cicd } shape.
+async function convertLegacyTemplatedJson(rawConfig, templatePath, options) {
+  const templated = {};
+  const cicd = {};
+
+  for (const pipelineFile of Object.keys(rawConfig)) {
+    templated[pipelineFile] = {};
+    for (const varname of Object.keys(rawConfig[pipelineFile])) {
+      const { pkgMap, cicdEntries } = await convertLegacyEntry(rawConfig[pipelineFile][varname], templatePath, options);
+      templated[pipelineFile][varname] = pkgMap;
+      Object.assign(cicd, cicdEntries);
+    }
+  }
+
+  return { templated, cicd };
+}
+
+// ---------------------------------------------------------------------------
+// Discover packages not yet assigned to any template and add them, using
+// detected package type + the existing convention (same packageFolder, else
+// same output type, else the default "PACKAGES" placeholder). Mutates
+// `templated`/`cicd` in place; returns true if anything was added.
+// ---------------------------------------------------------------------------
+async function detectAndAssignNewPackages(templated, cicd, options, templatePath) {
+  const assigned = collectAssignedPackages(templated);
+  const buildTemplateFiles = listBuildTemplateFiles(templatePath);
+
+  const pkgPaths = await globby(buildPackageJsonGlob(options.children), {
+    cwd: process.cwd(),
+    ignore: ['**/node_modules/**', '**/tests/**'],
+    absolute: true,
   });
+
+  let added = false;
+
+  pkgPaths.forEach(pkgPath => {
+    let pkg;
+    try { pkg = JSON.parse(readFileSync(pkgPath, 'utf8')); } catch { return; }
+    if (!pkg.name || !pkg.version || assigned.has(pkg.name)) return;
+
+    const folderName = path.basename(path.dirname(pkgPath));
+    if (options.exclude.includes(folderName)) return;
+
+    const packageFolder = path.basename(path.dirname(path.dirname(pkgPath)));
+    const detected = detectCicdType(pkg.name, pkg, pkgPath);
+    const { pipelineFile, placeholder, template } = chooseAssignmentForNewPackage({
+      packageFolder,
+      output: detected ? detected.output : undefined,
+      templated,
+      cicd,
+      buildTemplateFiles,
+    });
+
+    if (!template) return;
+
+    templated[pipelineFile] = templated[pipelineFile] || {};
+    templated[pipelineFile][placeholder] = templated[pipelineFile][placeholder] || {};
+    templated[pipelineFile][placeholder][pkg.name] = template;
+    cicd[pkg.name] = { ...(cicd[pkg.name] || {}), folderName, packageFolder };
+    assigned.add(pkg.name);
+    added = true;
+  });
+
+  return added;
 }
 
 // ---------------------------------------------------------------------------
 // main
 // ---------------------------------------------------------------------------
 async function main(options) {
+  // Detect workspace package roots (pnpm-workspace.yaml or package.json
+  // workspaces), same as monorepo-version and manifest. Used below to scope
+  // discovery of new (not-yet-configured) packages.
+  if (!options.children) {
+    const detected = resolveWorkspaceChildren(process.cwd());
+    if (detected) {
+      if (options.debug) console.log(`Auto-detected workspace children: ${detected}`);
+      options.children = detected;
+    }
+  }
+
+  // --exclude drops specific root directories from whichever children list is
+  // in effect, auto-detected or explicit. The same list is also used below to
+  // filter individual packages by folder name during generation.
+  if (options.exclude.length > 0) {
+    options.children = excludeChildren(options.children, options.exclude) || options.children;
+  }
+
   const configDir = options.platform === 'github' ? '.github' : '.cicd';
   const altConfigDir = options.platform === 'github' ? '.cicd' : '.github';
   const templatePath = path.join(process.cwd(), `${configDir}/templates`);
   const fallbackTemplatePath = path.join(process.cwd(), `${altConfigDir}/templates`);
 
-  // Try manifest.json first, then fall back to templated.json
   const manifestPath = path.join(process.cwd(), `${configDir}/manifest.json`);
   const templatedJsonPath = path.join(process.cwd(), `${configDir}/templates/templated.json`);
 
-  const useManifest = existsSync(manifestPath);
-  const useTemplatedJson = !useManifest && existsSync(templatedJsonPath);
-
-  if (!useManifest && !useTemplatedJson) {
-    throw `enablement-build-template-generate: could not find manifest.json at ${configDir}/manifest.json or templated.json at ${configDir}/templates/templated.json`;
+  // ── Load config: manifest.json's "templated" section (if still present, to
+  // be migrated out), else templated.json (new or legacy format). Whatever we
+  // load is normalized into { templated, cicd } once, up front, so generation
+  // below always runs the same (advanced-format) code path.
+  let templated;
+  let cicd;
+  let manifestToPersist = null; // set when manifest.json needs its "templated" section stripped
+  let templatedJsonDirty = false; // set when templated.json needs (re)writing
+  let dependencies = {}; // manifest.json's local dependency graph, for ordering generation
+
+  if (existsSync(manifestPath)) {
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8') || '{}');
+    dependencies = manifest.dependencies || {};
+    if (isAdvancedTemplatedFormat(manifest)) {
+      templated = manifest.templated;
+      cicd = extractGenerationCicd(manifest.cicd || {});
+      delete manifest.templated;
+      manifestToPersist = manifest;
+      templatedJsonDirty = true;
+    }
   }
 
-  let config;
-  let cicd = {};
+  if (!templated) {
+    if (!existsSync(templatedJsonPath)) {
+      throw `enablement-build-template-generate: could not find manifest.json "templated" section at ${configDir}/manifest.json or templated.json at ${configDir}/templates/templated.json`;
+    }
 
-  if (useManifest) {
-    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
-    if (!manifest.templated) {
-      throw `enablement-build-template-generate: manifest.json has no "templated" section`;
+    const raw = JSON.parse(readFileSync(templatedJsonPath, 'utf8') || '{}');
+    if (isAdvancedTemplatedFormat(raw)) {
+      templated = raw.templated;
+      cicd = raw.cicd || {};
+      if (typeof raw.version !== 'number') {
+        // Advanced format but predates the version field: write it back once,
+        // purely to backfill it, even if nothing else changed.
+        templatedJsonDirty = true;
+      }
+    } else {
+      const converted = await convertLegacyTemplatedJson(raw, templatePath, options);
+      templated = converted.templated;
+      cicd = converted.cicd;
+      templatedJsonDirty = true;
     }
-    config = manifest.templated;
-    cicd = manifest.cicd || {};
-  } else {
-    config = JSON.parse(readFileSync(templatedJsonPath, 'utf8'));
   }
 
+  // ── Discover packages not yet assigned to any template and add them.
+  if (await detectAndAssignNewPackages(templated, cicd, options, templatePath)) {
+    templatedJsonDirty = true;
+  }
+
+  // ── Persist. At most one write to each file, only when something changed.
+  if (manifestToPersist) {
+    writeFileSync(manifestPath, JSON.stringify(manifestToPersist, null, 2), 'utf8');
+  }
+  if (templatedJsonDirty) {
+    writeFileSync(templatedJsonPath, JSON.stringify({ version: TEMPLATED_JSON_ADVANCED_VERSION, templated, cicd }, null, 2), 'utf8');
+  }
+
+  // ── Generate.
   const plist = [];
 
-  Object.keys(config).forEach((templateFilename) => {
+  Object.keys(templated).forEach((templateFilename) => {
     plist.push(new Promise((primaryResolve, reject) => {
       try {
         const docTemplate = readFileSync(path.join(templatePath, templateFilename), 'utf8');
         const jlist = [];
 
-        Object.keys(config[templateFilename]).forEach((varname) => {
-          const varConfig = config[templateFilename][varname];
-
-          if (useManifest) {
-            // New format: varConfig is { pkgName: "template.yml" | [...] }
-            jlist.push(expandVarFromManifest(varname, varConfig, cicd, templatePath, fallbackTemplatePath, options));
-          } else {
-            // Legacy format: varConfig is { rootPath, template, exclude? }
-            jlist.push(expandVarFromTemplatedJson(varname, varConfig, templatePath, fallbackTemplatePath, options));
-          }
+        Object.keys(templated[templateFilename]).forEach((varname) => {
+          const varConfig = templated[templateFilename][varname];
+          jlist.push(expandVarFromManifest(varname, varConfig, cicd, templatePath, fallbackTemplatePath, options, dependencies));
         });
 
         Promise.all(jlist).then((results) => {
@@ -220,9 +346,10 @@ async function main(options) {
 // CLI
 // ---------------------------------------------------------------------------
 let options = {
-  platform: null,
+  platform: 'ado',
   exclude: [],
   debug: false,
+  children: null,
 };
 
 let argv = process.argv;
@@ -243,20 +370,6 @@ for (let i = 2; i < argv.length; i++) {
   }
 }
 
-if (!options.platform) {
-  const hasGithubManifest  = existsSync(path.join(process.cwd(), '.github/manifest.json'));
-  const hasAdoManifest     = existsSync(path.join(process.cwd(), '.cicd/manifest.json'));
-  const hasGithubTemplated = existsSync(path.join(process.cwd(), '.github/templates/templated.json'));
-  const hasAdoTemplated    = existsSync(path.join(process.cwd(), '.cicd/templates/templated.json'));
-
-  if (hasGithubManifest || hasGithubTemplated) {
-    options.platform = 'github';
-  } else if (hasAdoManifest || hasAdoTemplated) {
-    options.platform = 'ado';
-  } else {
-    options.platform = 'ado';
-  }
-}
 
 (async () => {
   try {

package/src/lib.mjs

@@ -1,4 +1,135 @@
 import path from 'path';
+import { readdirSync } from 'fs';
+import { detectCicdType } from 'enablement-build-manifest/src/detect.mjs';
+import { resolveWorkspaceChildren, buildPackageJsonGlob, excludeChildren } from 'enablement-build-manifest/src/workspace.mjs';
+
+// Re-exposes the manifest package's pure package-type detector (output/language/
+// tier/packageType from package.json shape or csproj/pyproject.toml/Dockerfile)
+// so template-generate can classify a package without needing manifest.json.
+export { detectCicdType };
+
+// Re-exposes the manifest package's workspace root-directory detector
+// (pnpm-workspace.yaml or package.json#workspaces), the exclude filter for it,
+// and the glob it implies, so template-generate can find package roots
+// without needing manifest.json.
+export { resolveWorkspaceChildren, buildPackageJsonGlob, excludeChildren };
+
+// Re-exposes the manifest package's dependency-order sort, so a package's
+// local dependencies (per manifest.json's "dependencies") are generated
+// before it, as much as possible.
+export { topologicalSort } from 'enablement-build-manifest/src/dependencyOrder.mjs';
+
+// ─── templated.json format helpers ───────────────────────────────────────────
+
+// templated.json schema versions. 1 = legacy rootPath+template shape, 2 = the
+// advanced { templated, cicd } shape. Every write stamps ADVANCED_VERSION;
+// LEGACY_VERSION is only ever inferred for older, unversioned files.
+export const TEMPLATED_JSON_LEGACY_VERSION = 1;
+export const TEMPLATED_JSON_ADVANCED_VERSION = 2;
+
+// True when parsed templated.json content is in the advanced format. An
+// explicit "version" property is authoritative and used exclusively — no
+// shape-sniffing once it's present. Only when "version" is absent do we infer
+// it from the legacy content's shape (a top-level "templated" key = advanced).
+export function isAdvancedTemplatedFormat(data) {
+  if (!data) return false;
+  if (typeof data.version === 'number') return data.version >= TEMPLATED_JSON_ADVANCED_VERSION;
+  return !!data.templated;
+}
+
+// Pick only the per-package fields generation needs (folderName, packageFolder,
+// metadata) out of a fuller manifest.json cicd map, dropping unrelated fields
+// like output/language/tier/packageType/hash/version.
+export function extractGenerationCicd(cicd = {}) {
+  const result = {};
+  Object.keys(cicd).forEach((pkgName) => {
+    const entry = cicd[pkgName] || {};
+    const picked = {};
+    if (entry.folderName) picked.folderName = entry.folderName;
+    if (entry.packageFolder) picked.packageFolder = entry.packageFolder;
+    if (entry.metadata) picked.metadata = entry.metadata;
+    result[pkgName] = picked;
+  });
+  return result;
+}
+
+// Collect every package name already assigned to a template anywhere in the
+// advanced-format templated map, across all pipeline files and placeholders.
+export function collectAssignedPackages(templated = {}) {
+  const names = new Set();
+  Object.values(templated).forEach((placeholders) => {
+    Object.values(placeholders || {}).forEach((pkgMap) => {
+      Object.keys(pkgMap || {}).forEach((name) => names.add(name));
+    });
+  });
+  return names;
+}
+
+// List "build" template files: underscore-prefixed .yml files in the templates
+// dir that aren't scan/check templates. Mirrors manifest.mjs's prior convention
+// for choosing a template by detected package type.
+export function listBuildTemplateFiles(templatePath) {
+  let files;
+  try {
+    files = readdirSync(templatePath);
+  } catch {
+    return [];
+  }
+  const withUnderscore = files.filter((f) => f.endsWith('.yml') && f.includes('_'));
+  return withUnderscore.filter((f) => !f.includes('scan') && !f.includes('check'));
+}
+
+// Map a detected cicd "output" value to the keyword used to pick a build template.
+function templateKeywordForOutput(output) {
+  if (output === 'pypi') return 'python';
+  if (output === 'nuget') return 'dotnet';
+  if (output === 'docker') return 'docker';
+  return 'node';
+}
+
+// Derive the best-fit build template for a detected output type.
+export function deriveTemplateForType(output, buildTemplateFiles) {
+  const lookfor = templateKeywordForOutput(output);
+  for (const file of buildTemplateFiles) {
+    if (file.includes(lookfor)) return file;
+  }
+  return buildTemplateFiles[0] || null;
+}
+
+// Choose where a newly-discovered package should be assigned, mirroring
+// manifest.mjs's prior convention:
+//   1. reuse the placeholder of an existing package under the same packageFolder
+//   2. else reuse the placeholder of an existing package of the same output type
+//   3. else fall back to the default "PACKAGES" placeholder on the first pipeline file
+export function chooseAssignmentForNewPackage({ packageFolder, output, templated, cicd, buildTemplateFiles }) {
+  const pipelineFiles = Object.keys(templated);
+  const primaryPipelineFile = pipelineFiles[0] || 'build.yml';
+
+  for (const pipelineFile of pipelineFiles) {
+    for (const [placeholder, pkgMap] of Object.entries(templated[pipelineFile] || {})) {
+      for (const existingName of Object.keys(pkgMap || {})) {
+        if ((cicd[existingName] || {}).packageFolder === packageFolder) {
+          return { pipelineFile, placeholder, template: pkgMap[existingName] };
+        }
+      }
+    }
+  }
+
+  const lookfor = templateKeywordForOutput(output);
+  for (const [placeholder, pkgMap] of Object.entries(templated[primaryPipelineFile] || {})) {
+    for (const tpl of Object.values(pkgMap || {})) {
+      if (typeof tpl === 'string' && tpl.toLowerCase().includes(lookfor)) {
+        return { pipelineFile: primaryPipelineFile, placeholder, template: tpl };
+      }
+    }
+  }
+
+  return {
+    pipelineFile: primaryPipelineFile,
+    placeholder: 'PACKAGES',
+    template: deriveTemplateForType(output, buildTemplateFiles),
+  };
+}
 
 // Priority order for version manifest files (lower index = higher priority)
 export const MANIFEST_PRIORITY = { 'package.json': 0, 'version.json': 1, 'pyproject.toml': 2 };

package/tests/index.test.mjs

@@ -88,9 +88,9 @@ function createFixtureWorkspace(mode, options = {}) {
   return tmpRoot;
 }
 
-function runGenerator(cwd) {
+function runGenerator(cwd, extraArgs = []) {
   const scriptPath = fileURLToPath(new URL('../src/index.mjs', import.meta.url));
-  execFileSync(process.execPath, [scriptPath, '--platform', 'ado'], {
+  execFileSync(process.execPath, [scriptPath, '--platform', 'ado', ...extraArgs], {
     cwd,
     stdio: 'pipe',
   });
@@ -183,3 +183,363 @@ describe('template-generate mode parity', () => {
     }
   });
 });
+
+describe('templated.json migration', () => {
+  it("migrates manifest.json's templated section into templated.json and strips it from manifest.json", () => {
+    const root = createFixtureWorkspace('manifest');
+    try {
+      runGenerator(root);
+
+      const manifest = JSON.parse(readFileSync(path.join(root, '.cicd', 'manifest.json'), 'utf8'));
+      expect(manifest.templated).toBeUndefined();
+
+      const templatedJson = JSON.parse(readFileSync(path.join(root, '.cicd', 'templates', 'templated.json'), 'utf8'));
+      expect(templatedJson.templated['build.yml'].PACKAGES['@scope/enablement-build-alpha-lib']).toBe('job.yml');
+      expect(templatedJson.templated['build.yml'].PACKAGES['enablement-build-beta-tool']).toBe('job.yml');
+      expect(templatedJson.cicd['@scope/enablement-build-alpha-lib'].packageFolder).toBe('packages');
+      expect(templatedJson.version).toBe(2);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('converts a legacy templated.json to the new format on disk', () => {
+    const root = createFixtureWorkspace('legacy');
+    try {
+      runGenerator(root);
+
+      const templatedJson = JSON.parse(readFileSync(path.join(root, '.cicd', 'templates', 'templated.json'), 'utf8'));
+      expect(templatedJson.templated['build.yml'].PACKAGES['@scope/enablement-build-alpha-lib']).toBe('job.yml');
+      expect(templatedJson.templated['build.yml'].PACKAGES['enablement-build-beta-tool']).toBe('job.yml');
+      expect(templatedJson.cicd['@scope/enablement-build-alpha-lib']).toEqual({ folderName: 'alpha-lib', packageFolder: 'packages' });
+      expect(templatedJson.cicd['enablement-build-beta-tool']).toEqual({ folderName: 'beta-tool', packageFolder: 'packages' });
+      expect(templatedJson.version).toBe(2);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('backfills the version field on an unversioned advanced-format templated.json, even when nothing else changed', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'template-generate-'));
+    try {
+      mkdirSync(path.join(root, '.cicd', 'templates'), { recursive: true });
+      mkdirSync(path.join(root, 'packages', 'existing-lib'), { recursive: true });
+
+      writeJson(path.join(root, 'packages', 'existing-lib', 'package.json'), {
+        name: 'existing-lib',
+        version: '1.0.0',
+      });
+
+      writeFileSync(path.join(root, '.cicd', 'templates', 'build.yml'), 'jobs:\n{PACKAGES}\n', 'utf8');
+      writeFileSync(
+        path.join(root, '.cicd', 'templates', 'job.yml'),
+        '- job: build_{safe}\n  displayName: NAME={name}\n',
+        'utf8'
+      );
+
+      // Advanced format already, but predates the version field.
+      writeJson(path.join(root, '.cicd', 'templates', 'templated.json'), {
+        templated: { 'build.yml': { PACKAGES: { 'existing-lib': 'job.yml' } } },
+        cicd: { 'existing-lib': { folderName: 'existing-lib', packageFolder: 'packages' } },
+      });
+
+      const firstOut = runGenerator(root);
+      const templatedAfter = JSON.parse(readFileSync(path.join(root, '.cicd', 'templates', 'templated.json'), 'utf8'));
+
+      expect(templatedAfter.version).toBe(2);
+      expect(templatedAfter.templated['build.yml'].PACKAGES['existing-lib']).toBe('job.yml');
+
+      // Running again is now a true no-op: same output, same file.
+      const secondOut = runGenerator(root);
+      const templatedAfterSecond = JSON.parse(readFileSync(path.join(root, '.cicd', 'templates', 'templated.json'), 'utf8'));
+      expect(secondOut).toBe(firstOut);
+      expect(templatedAfterSecond).toEqual(templatedAfter);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('detects a new package, assigns it a template by type, and leaves existing packages untouched', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'template-generate-'));
+    try {
+      mkdirSync(path.join(root, '.cicd', 'templates'), { recursive: true });
+      mkdirSync(path.join(root, 'packages', 'existing-lib'), { recursive: true });
+      mkdirSync(path.join(root, 'apps', 'new-svc'), { recursive: true });
+
+      writeJson(path.join(root, 'packages', 'existing-lib', 'package.json'), {
+        name: 'existing-lib',
+        version: '1.0.0',
+      });
+      writeJson(path.join(root, 'apps', 'new-svc', 'package.json'), {
+        name: 'new-svc',
+        version: '1.0.0',
+        main: 'index.js',
+      });
+
+      writeFileSync(path.join(root, '.cicd', 'templates', 'build.yml'), 'jobs:\n{PACKAGES}\n', 'utf8');
+      writeFileSync(
+        path.join(root, '.cicd', 'templates', 'job.yml'),
+        '- job: build_{safe}\n  displayName: NAME={name}\n',
+        'utf8'
+      );
+      writeFileSync(
+        path.join(root, '.cicd', 'templates', '_build_node_package.yml'),
+        '- job: node_{safe}\n  displayName: NAME={name}\n',
+        'utf8'
+      );
+
+      writeJson(path.join(root, '.cicd', 'templates', 'templated.json'), {
+        templated: {
+          'build.yml': {
+            PACKAGES: { 'existing-lib': 'job.yml' },
+          },
+        },
+        cicd: {
+          'existing-lib': { folderName: 'existing-lib', packageFolder: 'packages' },
+        },
+      });
+
+      const firstOut = runGenerator(root);
+      const templatedAfterFirst = JSON.parse(readFileSync(path.join(root, '.cicd', 'templates', 'templated.json'), 'utf8'));
+
+      // Existing package untouched.
+      expect(templatedAfterFirst.templated['build.yml'].PACKAGES['existing-lib']).toBe('job.yml');
+      expect(templatedAfterFirst.cicd['existing-lib']).toEqual({ folderName: 'existing-lib', packageFolder: 'packages' });
+
+      // New package detected, classified as a node package, and assigned the node build template.
+      expect(templatedAfterFirst.templated['build.yml'].PACKAGES['new-svc']).toBe('_build_node_package.yml');
+      expect(templatedAfterFirst.cicd['new-svc']).toEqual({ folderName: 'new-svc', packageFolder: 'apps' });
+
+      expect(firstOut).toContain('NAME=existing-lib');
+      expect(firstOut).toContain('NAME=new-svc');
+
+      // Second run: nothing new to detect, output and config are stable.
+      const secondOut = runGenerator(root);
+      const templatedAfterSecond = JSON.parse(readFileSync(path.join(root, '.cicd', 'templates', 'templated.json'), 'utf8'));
+
+      expect(secondOut).toBe(firstOut);
+      expect(templatedAfterSecond).toEqual(templatedAfterFirst);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('template-generate new-package assignment convention', () => {
+  it('reuses the placeholder/template of an existing package under the same packageFolder (tier 1)', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'template-generate-'));
+    try {
+      mkdirSync(path.join(root, '.cicd', 'templates'), { recursive: true });
+      mkdirSync(path.join(root, 'packages', 'new-a'), { recursive: true });
+
+      writeJson(path.join(root, 'packages', 'new-a', 'package.json'), { name: 'new-a', version: '1.0.0', main: 'index.js' });
+
+      writeFileSync(path.join(root, '.cicd', 'templates', 'build.yml'), 'jobs:\n{PACKAGES}\n', 'utf8');
+      writeFileSync(path.join(root, '.cicd', 'templates', 'job.yml'), '- job: build_{safe}\n', 'utf8');
+      writeFileSync(path.join(root, '.cicd', 'templates', 'custom.yml'), '- job: custom_{safe}\n', 'utf8');
+      // No "_build_*" template files exist at all — if this fell through to the
+      // type-derived fallback, there'd be nothing to assign and new-a would be skipped.
+
+      writeJson(path.join(root, '.cicd', 'templates', 'templated.json'), {
+        templated: { 'build.yml': { PACKAGES: { 'existing-a': 'custom.yml' } } },
+        cicd: { 'existing-a': { folderName: 'existing-a', packageFolder: 'packages' } },
+      });
+
+      const out = runGenerator(root, ['--children', 'packages']);
+
+      const templatedJson = JSON.parse(readFileSync(path.join(root, '.cicd', 'templates', 'templated.json'), 'utf8'));
+      expect(templatedJson.templated['build.yml'].PACKAGES['new-a']).toBe('custom.yml');
+      expect(templatedJson.cicd['new-a']).toEqual({ folderName: 'new-a', packageFolder: 'packages' });
+      expect(out).toContain('custom_newa');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('reuses the placeholder/template of an existing package of the same output type when packageFolder differs (tier 2)', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'template-generate-'));
+    try {
+      mkdirSync(path.join(root, '.cicd', 'templates'), { recursive: true });
+      mkdirSync(path.join(root, 'apps', 'new-node-app'), { recursive: true });
+
+      writeJson(path.join(root, 'apps', 'new-node-app', 'package.json'), { name: 'new-node-app', version: '1.0.0', main: 'index.js' });
+
+      writeFileSync(path.join(root, '.cicd', 'templates', 'build.yml'), 'jobs:\n{PACKAGES}\n{SERVICES}\n', 'utf8');
+      writeFileSync(path.join(root, '.cicd', 'templates', '_build_node_package.yml'), '- job: node_{safe}\n', 'utf8');
+
+      // existing-node-lib lives under a different packageFolder ("services"),
+      // so tier 1 (same packageFolder) cannot match new-node-app ("apps").
+      // It's assigned a template containing "node" under a non-default
+      // placeholder ("SERVICES"), which tier 2 should reuse verbatim.
+      writeJson(path.join(root, '.cicd', 'templates', 'templated.json'), {
+        templated: {
+          'build.yml': {
+            PACKAGES: {},
+            SERVICES: { 'existing-node-lib': '_build_node_package.yml' },
+          },
+        },
+        cicd: {
+          'existing-node-lib': { folderName: 'existing-node-lib', packageFolder: 'services' },
+        },
+      });
+
+      runGenerator(root, ['--children', 'apps']);
+
+      const templatedJson = JSON.parse(readFileSync(path.join(root, '.cicd', 'templates', 'templated.json'), 'utf8'));
+      // Landed in SERVICES (existing-node-lib's placeholder), not the PACKAGES
+      // default — proving reuse-by-type (tier 2), not the type-derived fallback (tier 3).
+      expect(templatedJson.templated['build.yml'].SERVICES['new-node-app']).toBe('_build_node_package.yml');
+      expect(templatedJson.templated['build.yml'].PACKAGES['new-node-app']).toBeUndefined();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('template-generate --children', () => {
+  it('scopes new-package scanning to an explicit --children list, overriding the broad-scan default', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'template-generate-'));
+    try {
+      mkdirSync(path.join(root, '.cicd', 'templates'), { recursive: true });
+      mkdirSync(path.join(root, 'packages', 'existing-lib'), { recursive: true });
+      mkdirSync(path.join(root, 'tools', 'skip-me'), { recursive: true });
+
+      // No pnpm-workspace.yaml / package.json#workspaces declared at all, so
+      // without --children this would broad-scan and find "tools/skip-me" too.
+      writeJson(path.join(root, 'packages', 'existing-lib', 'package.json'), { name: 'existing-lib', version: '1.0.0' });
+      writeJson(path.join(root, 'tools', 'skip-me', 'package.json'), { name: 'skip-me', version: '1.0.0', main: 'index.js' });
+
+      writeFileSync(path.join(root, '.cicd', 'templates', 'build.yml'), 'jobs:\n{PACKAGES}\n', 'utf8');
+      writeFileSync(path.join(root, '.cicd', 'templates', 'job.yml'), '- job: build_{safe}\n  displayName: NAME={name}\n', 'utf8');
+
+      writeJson(path.join(root, '.cicd', 'templates', 'templated.json'), {
+        templated: { 'build.yml': { PACKAGES: { 'existing-lib': 'job.yml' } } },
+        cicd: { 'existing-lib': { folderName: 'existing-lib', packageFolder: 'packages' } },
+      });
+
+      runGenerator(root, ['--children', 'packages']);
+
+      const templatedJson = JSON.parse(readFileSync(path.join(root, '.cicd', 'templates', 'templated.json'), 'utf8'));
+      expect(templatedJson.templated['build.yml'].PACKAGES['existing-lib']).toBe('job.yml');
+      expect(templatedJson.templated['build.yml'].PACKAGES['skip-me']).toBeUndefined();
+      expect(templatedJson.cicd['skip-me']).toBeUndefined();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('template-generate --exclude', () => {
+  it('drops an excluded root directory from auto-detected new-package scanning', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'template-generate-'));
+    try {
+      mkdirSync(path.join(root, '.cicd', 'templates'), { recursive: true });
+      mkdirSync(path.join(root, 'packages', 'existing-lib'), { recursive: true });
+      mkdirSync(path.join(root, 'tools', 'skip-me'), { recursive: true });
+
+      writeJson(path.join(root, 'package.json'), {
+        name: 'tmp-monorepo',
+        private: true,
+        workspaces: ['packages/*', 'tools/*'],
+      });
+      writeJson(path.join(root, 'packages', 'existing-lib', 'package.json'), { name: 'existing-lib', version: '1.0.0' });
+      writeJson(path.join(root, 'tools', 'skip-me', 'package.json'), { name: 'skip-me', version: '1.0.0', main: 'index.js' });
+
+      writeFileSync(path.join(root, '.cicd', 'templates', 'build.yml'), 'jobs:\n{PACKAGES}\n', 'utf8');
+      writeFileSync(path.join(root, '.cicd', 'templates', 'job.yml'), '- job: build_{safe}\n  displayName: NAME={name}\n', 'utf8');
+
+      writeJson(path.join(root, '.cicd', 'templates', 'templated.json'), {
+        templated: { 'build.yml': { PACKAGES: { 'existing-lib': 'job.yml' } } },
+        cicd: { 'existing-lib': { folderName: 'existing-lib', packageFolder: 'packages' } },
+      });
+
+      runGenerator(root, ['--exclude', 'tools']);
+
+      const templatedJson = JSON.parse(readFileSync(path.join(root, '.cicd', 'templates', 'templated.json'), 'utf8'));
+      expect(templatedJson.templated['build.yml'].PACKAGES['existing-lib']).toBe('job.yml');
+      expect(templatedJson.templated['build.yml'].PACKAGES['skip-me']).toBeUndefined();
+      expect(templatedJson.cicd['skip-me']).toBeUndefined();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('template-generate dependency ordering', () => {
+  it('generates a dependency before its dependent, per manifest.json dependencies', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'template-generate-'));
+    try {
+      mkdirSync(path.join(root, '.cicd', 'templates'), { recursive: true });
+
+      writeFileSync(path.join(root, '.cicd', 'templates', 'build.yml'), 'jobs:\n{PACKAGES}\n', 'utf8');
+      writeFileSync(path.join(root, '.cicd', 'templates', 'job.yml'), '- job: build_{safe}\n', 'utf8');
+
+      // Assignment order deliberately does not match dependency order:
+      // pkg-a depends on pkg-b depends on pkg-c, but keys are alphabetical.
+      writeJson(path.join(root, '.cicd', 'templates', 'templated.json'), {
+        templated: {
+          'build.yml': {
+            PACKAGES: { 'pkg-a': 'job.yml', 'pkg-b': 'job.yml', 'pkg-c': 'job.yml' },
+          },
+        },
+        cicd: {
+          'pkg-a': { folderName: 'pkg-a', packageFolder: 'packages' },
+          'pkg-b': { folderName: 'pkg-b', packageFolder: 'packages' },
+          'pkg-c': { folderName: 'pkg-c', packageFolder: 'packages' },
+        },
+      });
+
+      // manifest.json here only supplies the dependency graph (no "templated").
+      writeJson(path.join(root, '.cicd', 'manifest.json'), {
+        dependencies: {
+          'pkg-a': ['pkg-b'],
+          'pkg-b': ['pkg-c'],
+          'pkg-c': [],
+        },
+      });
+
+      const out = runGenerator(root);
+
+      const posA = out.indexOf('build_pkga');
+      const posB = out.indexOf('build_pkgb');
+      const posC = out.indexOf('build_pkgc');
+
+      expect(posC).toBeLessThan(posB);
+      expect(posB).toBeLessThan(posA);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('template-generate --exclude (generation-side)', () => {
+  it('omits an already-assigned package from the generated output by folder name', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'template-generate-'));
+    try {
+      mkdirSync(path.join(root, '.cicd', 'templates'), { recursive: true });
+
+      writeFileSync(path.join(root, '.cicd', 'templates', 'build.yml'), 'jobs:\n{PACKAGES}\n', 'utf8');
+      writeFileSync(path.join(root, '.cicd', 'templates', 'job.yml'), '- job: build_{safe}\n', 'utf8');
+
+      writeJson(path.join(root, '.cicd', 'templates', 'templated.json'), {
+        version: 2,
+        templated: {
+          'build.yml': {
+            PACKAGES: { 'keep-me': 'job.yml', 'drop-me': 'job.yml' },
+          },
+        },
+        cicd: {
+          'keep-me': { folderName: 'keep-me', packageFolder: 'packages' },
+          'drop-me': { folderName: 'drop-me', packageFolder: 'packages' },
+        },
+      });
+
+      const out = runGenerator(root, ['--exclude', 'drop-me']);
+
+      expect(out).toContain('build_keepme');
+      expect(out).not.toContain('build_dropme');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/tests/lib.test.mjs

@@ -1,4 +1,7 @@
 import { describe, it, expect } from '@jest/globals';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs';
+import os from 'os';
+import path from 'path';
 import {
   MANIFEST_PRIORITY,
   stripWhitespace,
@@ -12,6 +15,12 @@ import {
   resolveOtherPlaceholders,
   applyVarsToDocTemplate,
   wrapWithBanner,
+  isAdvancedTemplatedFormat,
+  extractGenerationCicd,
+  collectAssignedPackages,
+  listBuildTemplateFiles,
+  deriveTemplateForType,
+  chooseAssignmentForNewPackage,
 } from '../src/lib.mjs';
 
 // ─── MANIFEST_PRIORITY ────────────────────────────────────────────────────────
@@ -354,3 +363,202 @@ describe('wrapWithBanner', () => {
     expect(result).toContain('\n\nbody\n\n');
   });
 });
+
+// ─── isAdvancedTemplatedFormat ────────────────────────────────────────────────
+
+describe('isAdvancedTemplatedFormat', () => {
+  it('is true when a top-level "templated" key is present', () => {
+    expect(isAdvancedTemplatedFormat({ templated: {}, cicd: {} })).toBe(true);
+  });
+
+  it('is false for the legacy rootPath+template shape', () => {
+    expect(isAdvancedTemplatedFormat({ 'build.yml': { PACKAGES: { rootPath: '../packages', template: 'job.yml' } } })).toBe(false);
+  });
+
+  it('is false for null/undefined', () => {
+    expect(isAdvancedTemplatedFormat(null)).toBe(false);
+    expect(isAdvancedTemplatedFormat(undefined)).toBe(false);
+  });
+
+  it('uses an explicit version property exclusively, ignoring shape', () => {
+    // version says legacy even though a "templated" key is present.
+    expect(isAdvancedTemplatedFormat({ version: 1, templated: {} })).toBe(false);
+    // version says advanced even though the shape looks legacy.
+    expect(isAdvancedTemplatedFormat({ version: 2, 'build.yml': { PACKAGES: { rootPath: '../packages', template: 'job.yml' } } })).toBe(true);
+  });
+});
+
+// ─── extractGenerationCicd ────────────────────────────────────────────────────
+
+describe('extractGenerationCicd', () => {
+  it('keeps only folderName, packageFolder, and metadata', () => {
+    const result = extractGenerationCicd({
+      'pkg-a': {
+        output: 'npm',
+        language: 'JavaScript',
+        tier: 'component',
+        packageFolder: 'packages',
+        folderName: 'pkg-a',
+        metadata: { owner: 'team-a' },
+        hash: 'abc123',
+        version: '1.0.0',
+      },
+    });
+
+    expect(result).toEqual({
+      'pkg-a': {
+        packageFolder: 'packages',
+        folderName: 'pkg-a',
+        metadata: { owner: 'team-a' },
+      },
+    });
+  });
+
+  it('omits fields that are absent rather than including them as undefined', () => {
+    const result = extractGenerationCicd({ 'pkg-a': { output: 'npm' } });
+    expect(result['pkg-a']).toEqual({});
+    expect(Object.keys(result['pkg-a'])).toEqual([]);
+  });
+
+  it('handles an empty or missing map', () => {
+    expect(extractGenerationCicd({})).toEqual({});
+    expect(extractGenerationCicd()).toEqual({});
+  });
+});
+
+// ─── collectAssignedPackages ──────────────────────────────────────────────────
+
+describe('collectAssignedPackages', () => {
+  it('collects package names across pipeline files and placeholders', () => {
+    const result = collectAssignedPackages({
+      'build.yml': {
+        PACKAGES: { 'pkg-a': 'job.yml', 'pkg-b': 'job.yml' },
+        OTHER: { 'pkg-c': 'job2.yml' },
+      },
+      'scan.yml': {
+        PACKAGES: { 'pkg-a': 'scan.yml' },
+      },
+    });
+
+    expect(result).toEqual(new Set(['pkg-a', 'pkg-b', 'pkg-c']));
+  });
+
+  it('returns an empty set for an empty map', () => {
+    expect(collectAssignedPackages({})).toEqual(new Set());
+  });
+});
+
+// ─── listBuildTemplateFiles ───────────────────────────────────────────────────
+
+describe('listBuildTemplateFiles', () => {
+  function tmpTemplatesDir(files) {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'lib-tests-'));
+    mkdirSync(path.join(root, 'templates'), { recursive: true });
+    for (const f of files) writeFileSync(path.join(root, 'templates', f), '', 'utf8');
+    return path.join(root, 'templates');
+  }
+
+  it('keeps underscore-prefixed build templates, excluding scan/check', () => {
+    const dir = tmpTemplatesDir([
+      '_build_node_package.yml',
+      '_build_dotnet_package.yml',
+      '_scan_node.yml',
+      '_check_code.yml',
+      'build.yml',
+      'notes.txt',
+    ]);
+    try {
+      expect(listBuildTemplateFiles(dir).sort()).toEqual(['_build_dotnet_package.yml', '_build_node_package.yml']);
+    } finally {
+      rmSync(path.dirname(dir), { recursive: true, force: true });
+    }
+  });
+
+  it('returns an empty array when the templates dir does not exist', () => {
+    expect(listBuildTemplateFiles('/does/not/exist')).toEqual([]);
+  });
+});
+
+// ─── deriveTemplateForType ────────────────────────────────────────────────────
+
+describe('deriveTemplateForType', () => {
+  const files = ['_build_node_package.yml', '_build_python_package.yml', '_build_dotnet_package.yml', '_build_docker_package.yml'];
+
+  it('picks the matching build template per output type', () => {
+    expect(deriveTemplateForType('npm', files)).toBe('_build_node_package.yml');
+    expect(deriveTemplateForType('pypi', files)).toBe('_build_python_package.yml');
+    expect(deriveTemplateForType('nuget', files)).toBe('_build_dotnet_package.yml');
+    expect(deriveTemplateForType('docker', files)).toBe('_build_docker_package.yml');
+  });
+
+  it('falls back to the first build template for an unknown output type', () => {
+    expect(deriveTemplateForType('something-else', ['_build_dotnet_package.yml'])).toBe('_build_dotnet_package.yml');
+  });
+
+  it('returns null when there are no build templates', () => {
+    expect(deriveTemplateForType('npm', [])).toBeNull();
+  });
+});
+
+// ─── chooseAssignmentForNewPackage ────────────────────────────────────────────
+
+describe('chooseAssignmentForNewPackage', () => {
+  const buildTemplateFiles = ['_build_node_package.yml', '_build_python_package.yml'];
+
+  it('reuses the placeholder of an existing package under the same packageFolder', () => {
+    const templated = { 'build.yml': { PACKAGES: { 'pkg-a': 'job.yml' } } };
+    const cicd = { 'pkg-a': { packageFolder: 'packages' } };
+
+    const result = chooseAssignmentForNewPackage({
+      packageFolder: 'packages',
+      output: 'pypi',
+      templated,
+      cicd,
+      buildTemplateFiles,
+    });
+
+    expect(result).toEqual({ pipelineFile: 'build.yml', placeholder: 'PACKAGES', template: 'job.yml' });
+  });
+
+  it('reuses the placeholder of a package with the same output type when no folder match exists', () => {
+    const templated = { 'build.yml': { NODE_JOBS: { 'pkg-a': '_build_node_package.yml' } } };
+    const cicd = { 'pkg-a': { packageFolder: 'apps' } };
+
+    const result = chooseAssignmentForNewPackage({
+      packageFolder: 'packages',
+      output: 'npm',
+      templated,
+      cicd,
+      buildTemplateFiles,
+    });
+
+    expect(result).toEqual({ pipelineFile: 'build.yml', placeholder: 'NODE_JOBS', template: '_build_node_package.yml' });
+  });
+
+  it('falls back to the default PACKAGES placeholder with a type-derived template', () => {
+    const templated = { 'build.yml': {} };
+    const cicd = {};
+
+    const result = chooseAssignmentForNewPackage({
+      packageFolder: 'packages',
+      output: 'pypi',
+      templated,
+      cicd,
+      buildTemplateFiles,
+    });
+
+    expect(result).toEqual({ pipelineFile: 'build.yml', placeholder: 'PACKAGES', template: '_build_python_package.yml' });
+  });
+
+  it('defaults to build.yml when there is no pipeline file yet', () => {
+    const result = chooseAssignmentForNewPackage({
+      packageFolder: 'packages',
+      output: 'npm',
+      templated: {},
+      cicd: {},
+      buildTemplateFiles,
+    });
+
+    expect(result).toEqual({ pipelineFile: 'build.yml', placeholder: 'PACKAGES', template: '_build_node_package.yml' });
+  });
+});