enablement-build-template-generate 1.0.19 → 1.3.0

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

@@ -0,0 +1,545 @@
+import { describe, it, expect } from '@jest/globals';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'fs';
+import os from 'os';
+import path from 'path';
+import { execFileSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+function writeJson(filePath, data) {
+  writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+
+function createFixtureWorkspace(mode, options = {}) {
+  const tmpRoot = mkdtempSync(path.join(os.tmpdir(), 'template-generate-'));
+
+  const defaultJobTemplateLines = [
+    '- job: build_{safe}',
+    '  displayName: NAME={name}',
+    '  safe: SAFE={safe}',
+    '  package: PKG={package}',
+    '  full: FULL={full}',
+    '  other: OTHER={other}',
+    "  script: cd ./{path}/{name}",
+    "  condition: contains(variables['changed'], '{name}')",
+    '',
+  ];
+
+  const jobTemplateLines = options.jobTemplateLines || defaultJobTemplateLines;
+
+  mkdirSync(path.join(tmpRoot, '.cicd', 'templates'), { recursive: true });
+  mkdirSync(path.join(tmpRoot, 'packages', 'alpha-lib'), { recursive: true });
+  mkdirSync(path.join(tmpRoot, 'packages', 'beta-tool'), { recursive: true });
+
+  writeJson(path.join(tmpRoot, 'packages', 'alpha-lib', 'package.json'), {
+    name: '@scope/enablement-build-alpha-lib',
+    version: '1.0.0',
+  });
+  writeJson(path.join(tmpRoot, 'packages', 'beta-tool', 'package.json'), {
+    name: 'enablement-build-beta-tool',
+    version: '1.0.0',
+  });
+
+  writeFileSync(
+    path.join(tmpRoot, '.cicd', 'templates', 'build.yml'),
+    'jobs:\n{PACKAGES}\n',
+    'utf8'
+  );
+
+  writeFileSync(
+    path.join(tmpRoot, '.cicd', 'templates', 'job.yml'),
+    jobTemplateLines.join('\n'),
+    'utf8'
+  );
+
+  const cicdEntries = {
+    '@scope/enablement-build-alpha-lib': {
+      packageFolder: 'packages',
+      ...(options.metadataByPackage?.['@scope/enablement-build-alpha-lib'] || {}),
+    },
+    'enablement-build-beta-tool': {
+      packageFolder: 'packages',
+      ...(options.metadataByPackage?.['enablement-build-beta-tool'] || {}),
+    },
+  };
+
+  if (mode === 'manifest') {
+    writeJson(path.join(tmpRoot, '.cicd', 'manifest.json'), {
+      templated: {
+        'build.yml': {
+          PACKAGES: {
+            '@scope/enablement-build-alpha-lib': 'job.yml',
+            'enablement-build-beta-tool': 'job.yml',
+          },
+        },
+      },
+      cicd: cicdEntries,
+    });
+  } else {
+    writeJson(path.join(tmpRoot, '.cicd', 'templates', 'templated.json'), {
+      'build.yml': {
+        PACKAGES: {
+          rootPath: '../../packages',
+          template: 'job.yml',
+        },
+      },
+    });
+  }
+
+  return tmpRoot;
+}
+
+function runGenerator(cwd, extraArgs = []) {
+  const scriptPath = fileURLToPath(new URL('../src/index.mjs', import.meta.url));
+  execFileSync(process.execPath, [scriptPath, '--platform', 'ado', ...extraArgs], {
+    cwd,
+    stdio: 'pipe',
+  });
+
+  return readFileSync(path.join(cwd, '.cicd', 'build.yml'), 'utf8');
+}
+
+function stripBanner(content) {
+  return content
+    .split('\n')
+    .filter(
+      (line) =>
+        line !== '#######################################' &&
+        line !== '### DO NOT EDIT - THIS IS GENERATED ###'
+    )
+    .join('\n')
+    .trim();
+}
+
+function normalizeOutput(content, root) {
+  return stripBanner(content).split(root).join('<ROOT>');
+}
+
+describe('template-generate mode parity', () => {
+  it('expands placeholders consistently between manifest and templated.json modes', () => {
+    const manifestRoot = createFixtureWorkspace('manifest');
+    const legacyRoot = createFixtureWorkspace('legacy');
+
+    try {
+      const manifestOut = runGenerator(manifestRoot);
+      const legacyOut = runGenerator(legacyRoot);
+
+      expect(manifestOut).toContain('NAME=alpha-lib');
+      expect(manifestOut).toContain('NAME=beta-tool');
+      expect(manifestOut).toContain('SAFE=alphalib');
+      expect(manifestOut).toContain('SAFE=betatool');
+      expect(manifestOut).toContain('PKG=enablement-build-alpha-lib');
+      expect(manifestOut).toContain('PKG=enablement-build-beta-tool');
+      expect(manifestOut).toContain('FULL=@scope/enablement-build-alpha-lib');
+      expect(manifestOut).toContain('FULL=enablement-build-beta-tool');
+      expect(manifestOut).toContain(`OTHER=${manifestRoot}/packages/beta-tool`);
+      expect(manifestOut).toContain(`OTHER=${manifestRoot}/packages/alpha-lib`);
+      expect(manifestOut).toContain('script: cd ./packages/alpha-lib');
+      expect(manifestOut).toContain('script: cd ./packages/beta-tool');
+      expect(manifestOut).toContain("condition: contains(variables['changed'], 'alpha-lib')");
+      expect(manifestOut).toContain("condition: contains(variables['changed'], 'beta-tool')");
+
+      expect(normalizeOutput(manifestOut, manifestRoot)).toBe(normalizeOutput(legacyOut, legacyRoot));
+    } finally {
+      rmSync(manifestRoot, { recursive: true, force: true });
+      rmSync(legacyRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('applies custom metadata placeholders only in manifest mode', () => {
+    const options = {
+      jobTemplateLines: [
+        '- job: meta_{safe}',
+        '  owner: OWNER={owner}',
+        '  tier: TIER={tier}',
+        '  name: NAME={name}',
+        '',
+      ],
+      metadataByPackage: {
+        '@scope/enablement-build-alpha-lib': {
+          metadata: { owner: 'team-alpha', tier: 'gold' },
+        },
+      },
+    };
+
+    const manifestRoot = createFixtureWorkspace('manifest', options);
+    const legacyRoot = createFixtureWorkspace('legacy', options);
+
+    try {
+      const manifestOut = runGenerator(manifestRoot);
+      const legacyOut = runGenerator(legacyRoot);
+
+      expect(manifestOut).toContain('owner: OWNER=team-alpha');
+      expect(manifestOut).toContain('tier: TIER=gold');
+      expect(manifestOut).toContain('owner: OWNER={owner}');
+      expect(manifestOut).toContain('tier: TIER={tier}');
+
+      expect(legacyOut).not.toContain('owner: OWNER=team-alpha');
+      expect(legacyOut).not.toContain('tier: TIER=gold');
+      expect(legacyOut).toContain('owner: OWNER={owner}');
+      expect(legacyOut).toContain('tier: TIER={tier}');
+    } finally {
+      rmSync(manifestRoot, { recursive: true, force: true });
+      rmSync(legacyRoot, { recursive: true, force: true });
+    }
+  });
+});
+
+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 });
+    }
+  });
+});