enablement-build-template-generate 1.0.10 → 1.0.13

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Chris Doty
+Copyright (c) 2026 Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,4 +1,191 @@
-# enablement-build-deploy-version
-Gets package.json version and updates a deployment repo with the verison.
-
-
+# enablement-build-template-generate
+
+Generates pipeline YAML files for monorepos by expanding a job template once per package and stitching the results into a document template. Designed for Azure DevOps but works with any text-based pipeline format.
+
+## Usage
+
+```bash
+npx enablement-build-template-generate@latest [flags]
+```
+
+---
+
+## How it works
+
+1. **Read config** — Loads a JSON config file, auto-detected from `.github/templates/templated.json` or `.cicd/templates/templated.json` based on the presence of a `.github/` directory.
+2. **Discover packages** — Globs for `package.json`, `version.json`, and `pyproject.toml` under the configured `rootPath`. When multiple manifest files exist in the same folder, the highest-priority one is used (`package.json` → `version.json` → `pyproject.toml`). Results are sorted alphabetically by folder name.
+3. **Expand job template** — For each discovered package, reads the package name from its manifest and fills in placeholders in the job snippet template.
+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.
+
+---
+
+## CLI flags
+
+| Flag | Default | Description |
+|---|---|---|
+| `--config <path>` | auto-detect | Path to the JSON config file. Defaults to `.github/templates/templated.json` if a `.github/` directory exists, otherwise `.cicd/templates/templated.json`. Resolved relative to the package first, then relative to the working directory. |
+| `--platform <name>` | auto-detect | Force the platform: `ado` (Azure DevOps) or `github` (GitHub Actions). Auto-detected from the presence of a `.github/` directory at the working directory root. |
+| `--exclude <list>` | — | Comma- or space-separated list of package folder names to skip during generation. |
+| `--debug` | off | Print verbose output. |
+
+---
+
+## Config file format
+
+The config file is a JSON object. Each key is the **output filename** (relative to the directory above the template folder). Each value maps placeholder variable names to job configurations.
+
+```json
+{
+  "ci-build.yaml": {
+    "jobs": {
+      "template": "job-template.yaml",
+      "rootPath": "./packages",
+      "exclude": ["internal-tool"]
+    }
+  }
+}
+```
+
+| Field | Description |
+|---|---|
+| `template` | Path to the job snippet template, relative to the config file's directory. |
+| `rootPath` | Root directory to scan for `package.json` files, relative to the config file's directory. |
+| `exclude` | _(optional)_ Array of folder names to skip. |
+
+Multiple output files and multiple variables per output file are supported:
+
+```json
+{
+  "ci-components.yaml": {
+    "componentJobs": {
+      "template": "component-job.yaml",
+      "rootPath": "./components"
+    }
+  },
+  "ci-saas.yaml": {
+    "saasJobs": {
+      "template": "saas-job.yaml",
+      "rootPath": "./saas",
+      "exclude": ["saas-legacy"]
+    }
+  }
+}
+```
+
+---
+
+## Template placeholders
+
+### Document template
+
+The document template (the top-level YAML file) uses `{variableName}` placeholders that are replaced with the fully expanded set of job snippets:
+
+```yaml
+# ci-build.yaml (document template)
+stages:
+  - stage: Build
+    jobs:
+      {jobs}
+```
+
+### Supported manifest files
+
+Each subfolder is scanned for a version manifest in this priority order:
+
+| Priority | File | Format |
+|---|---|---|
+| 1 | `package.json` | JSON — `"name"` field |
+| 2 | `version.json` | JSON — same shape as `package.json` |
+| 3 | `pyproject.toml` | TOML — `name` field under `[project]` or `[tool.poetry]` |
+
+When multiple manifest files exist in the same folder the highest-priority one is used. If none contains a `name` field the folder name is used as a fallback.
+
+### Job template
+
+Each job snippet template is expanded once per package. The following placeholders are available:
+
+| Placeholder | Value |
+|---|---|
+| `{name}` | Package folder name (e.g. `my-component`) |
+| `{safe}` | Folder name with `-`, `_`, and `.` removed — safe for use as a YAML identifier (e.g. `mycomponent`) |
+| `{package}` | npm package name without scope prefix (e.g. `my-component` from `@scope/my-component`) |
+| `{full}` | Full npm package name including scope (e.g. `@scope/my-component`) |
+| `{path}` | The `rootPath` value with any leading `./` stripped |
+| `{other}` | Expands to a comma-separated list of paths to every **other** package in the same scan — useful for pipeline dependency declarations |
+
+Example job template:
+
+```yaml
+      - job: build_{safe}
+        displayName: Build {name}
+        steps:
+          - script: pnpm --filter {full} build
+```
+
+---
+
+## Directory layout
+
+Templates and config live inside a subfolder; generated files are written one level up.
+
+**Azure DevOps** (default when no `.github/` directory):
+```
+.cicd/
+├── ci-build.yaml          ← generated output
+└── templates/
+    ├── templated.json     ← config file
+    ├── document.yaml      ← document template
+    └── job.yaml           ← job snippet template
+```
+
+**GitHub Actions** (when `.github/` directory is present):
+```
+.github/
+├── ci-build.yaml          ← generated output
+└── templates/
+    ├── templated.json     ← config file
+    ├── document.yaml      ← document template
+    └── job.yaml           ← job snippet template
+```
+
+---
+
+## Typical pipeline usage
+
+Run the generator as a pipeline step before the build stage:
+
+```yaml
+- script: npx enablement-build-template-generate@latest
+  displayName: Generate pipeline YAML
+```
+
+With a custom config location:
+
+```bash
+npx enablement-build-template-generate@latest --config .azuredevops/templates/templated.json
+```
+
+Excluding specific packages:
+
+```bash
+npx enablement-build-template-generate@latest --exclude legacy-pkg,test-harness
+```
+
+---
+
+## Output format
+
+Generated files are wrapped in `DO NOT EDIT` banners. Edit the templates, not the output:
+
+```yaml
+#######################################
+### DO NOT EDIT - THIS IS GENERATED ###
+#######################################
+
+# ... generated content ...
+
+#######################################
+### DO NOT EDIT - THIS IS GENERATED ###
+#######################################
+```

package/package.json

@@ -1,17 +1,28 @@
 {
   "name": "enablement-build-template-generate",
-  "version": "1.0.10",
+  "version": "1.0.13",
   "description": "Generates build yaml for mono repos",
   "type": "module",
-  "module": "./index.js",
-  "main": "./index.js",
-  "bin": "./index.js",
+  "module": "./src/index.mjs",
+  "main": "./src/index.mjs",
+  "bin": "./src/index.mjs",
   "dependencies": {
     "globby": "^14.0.1"
   },
-  "scripts": {
-    "start": "node index.js"
+  "devDependencies": {
+    "jest": "^29.0.0"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/*.test.mjs"
+    ]
   },
   "license": "MIT",
-  "author": "Chris Doty"
+  "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

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+import * as url from 'url';
+import path from 'path';
+import { globby } from 'globby';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+
+import {
+  stripWhitespace,
+  parseManifestName,
+  buildSearchGlobs,
+  groupByFolder,
+  resolvePackageName,
+  makeSafe,
+  expandJobTemplate,
+  resolveOtherPlaceholders,
+  applyVarsToDocTemplate,
+  wrapWithBanner,
+} from './lib.mjs';
+
+const __dirname = url.fileURLToPath(new URL('.', import.meta.url));
+
+function readManifestName(filePath) {
+  const content = readFileSync(filePath, 'utf8');
+  const fileType = filePath.endsWith('.toml') ? 'toml' : 'json';
+  return parseManifestName(content, fileType);
+}
+
+async function main(options) {
+  let configFile = path.join(__dirname, options.config);
+  const try1 = configFile;
+
+  if (!existsSync(configFile)) {
+    configFile = path.join(options.config);
+  }
+
+  if (!existsSync(configFile)) {
+    throw `enablement-build-template-generate: could not load config file ${configFile}, also tried ${try1}`;
+  }
+
+  const templatePath = path.dirname(configFile);
+  const config = JSON.parse(readFileSync(configFile, 'utf8'));
+  const search = buildSearchGlobs(options.exclude);
+  const plist = [];
+
+  Object.keys(config).forEach((templateFilename) => {
+    plist.push(new Promise(async (primaryResolve, reject) => {
+      const docTemplate = readFileSync(path.join(templatePath, templateFilename), 'utf8');
+      const jlist = [];
+
+      Object.keys(config[templateFilename]).forEach((varname) => {
+        const jobConfig = config[templateFilename][varname];
+        const job = new Promise(async (resolve, reject) => {
+          const jobTemplate = readFileSync(path.join(templatePath, jobConfig.template), 'utf8');
+          const cwd = path.join(templatePath, jobConfig.rootPath);
+          const jobRoot = jobConfig.rootPath.replace(/^[\.\/\\]+/, '');
+          const exclude = jobConfig.exclude || [];
+
+          globby(search, { cwd }).then((images) => {
+            images.sort();
+            const folderBest = groupByFolder(images);
+            const allNames = Object.keys(folderBest).sort()
+              .filter(name => !name.startsWith('_') && !exclude.includes(name));
+
+            const expandedJobs = allNames.map(name => {
+              const fullName = readManifestName(path.join(cwd, folderBest[name].filePath)) || name;
+              const packageName = resolvePackageName(fullName);
+              const safe = makeSafe(name);
+              return expandJobTemplate(jobTemplate, { name, safe, packageName, fullName, jobRoot });
+            });
+
+            let jobs = resolveOtherPlaceholders(expandedJobs.join('\n'), allNames, cwd);
+            resolve({ name: varname, text: jobs });
+          }, reject);
+        });
+        jlist.push(job);
+      });
+
+      Promise.all(jlist).then((results) => {
+        const output = applyVarsToDocTemplate(docTemplate, results);
+        const wrapped = wrapWithBanner(output);
+
+        if (stripWhitespace(wrapped) !== docTemplate) {
+          writeFileSync(path.join(templatePath, `../${templateFilename}`), wrapped, 'utf8');
+        }
+
+        primaryResolve(`generated template ${templateFilename}`);
+      }, reject);
+    }));
+  });
+
+  return Promise.all(plist);
+}
+
+let options = {
+  config: null,
+  platform: null,
+  exclude: [],
+  debug: false,
+};
+
+let argv = process.argv;
+
+for (let i = 2; i < argv.length; i++) {
+  if (argv[i] === '--debug') { options.debug = true; continue; }
+  if (argv[i].substring(0, 2) === '--') {
+    const name = argv[i].substring(2);
+    if (name === 'exclude') {
+      options[name] = argv[i + 1].replace(/\s/g, ',').split(',');
+      i++;
+    } else if (options[name] !== undefined) {
+      options[name] = argv[i + 1];
+      i++;
+    } else {
+      console.error('Expected a known option');
+      process.exit(1);
+    }
+  }
+}
+
+if (!options.platform) {
+  options.platform = existsSync(path.join(process.cwd(), '.github')) ? 'github' : 'ado';
+}
+if (!options.config) {
+  options.config = options.platform === 'github'
+    ? '.github/templates/templated.json'
+    : '.cicd/templates/templated.json';
+}
+
+(async () => {
+  try {
+    console.log('\x1b[32m%s\x1b[0m', 'Running enablement-build-template-generate with options:\n', JSON.stringify(options, null, 2));
+    const results = await main(options);
+    console.log(results.join('\n'));
+    if (options.debug) console.log('DONE');
+    process.exit(0);
+  } catch (e) {
+    console.log('\x1b[32m%s\x1b[0m', e);
+    if (options.debug) console.log('ERROR');
+    process.exit(1);
+  }
+})();

package/src/lib.mjs

@@ -0,0 +1,111 @@
+import path from 'path';
+
+// Priority order for version manifest files (lower index = higher priority)
+export const MANIFEST_PRIORITY = { 'package.json': 0, 'version.json': 1, 'pyproject.toml': 2 };
+
+// Strip all whitespace characters from a string
+export function stripWhitespace(str) {
+  return str.replace(/( |\r\n|\n|\r)/gm, '');
+}
+
+// Read the package name from pyproject.toml content (supports [project] and [tool.poetry])
+export function readTomlName(content) {
+  const lines = content.split('\n');
+  let inSection = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    if (/^\[project\]$/.test(trimmed) || /^\[tool\.poetry\]$/.test(trimmed)) { inSection = true; continue; }
+    if (/^\[/.test(trimmed)) { inSection = false; continue; }
+    if (inSection) {
+      const m = trimmed.match(/^name\s*=\s*["']([^"']+)["']/);
+      if (m) return m[1];
+    }
+  }
+  return null;
+}
+
+// Parse a package name from manifest file content.
+// fileType must be 'toml' or 'json' (covers package.json and version.json).
+export function parseManifestName(content, fileType) {
+  if (fileType === 'toml') return readTomlName(content);
+  try { return JSON.parse(content).name || null; } catch { return null; }
+}
+
+// Build the globby search array from an exclude list of folder names.
+export function buildSearchGlobs(excludeList) {
+  const search = ['./**/package.json', './**/version.json', './**/pyproject.toml'];
+  for (const ex of excludeList) {
+    search.push(`!**/${ex}`);
+  }
+  search.push('!**/node_modules');
+  return search;
+}
+
+// Group globby-returned file paths by folder, keeping the highest-priority manifest per folder.
+// Input paths are relative to the cwd passed to globby.
+export function groupByFolder(filePaths) {
+  const folderBest = {};
+  for (const filePath of filePaths) {
+    const filename = path.basename(filePath);
+    const folder = filePath.slice(0, filePath.length - filename.length - 1);
+    const priority = MANIFEST_PRIORITY[filename] ?? 99;
+    if (!folderBest[folder] || priority < folderBest[folder].priority) {
+      folderBest[folder] = { filePath, priority };
+    }
+  }
+  return folderBest;
+}
+
+// Strip the npm scope prefix from a package name (e.g. '@scope/foo' → 'foo').
+export function resolvePackageName(fullName) {
+  if (fullName.startsWith('@')) return fullName.split('/')[1];
+  return fullName;
+}
+
+// Return a name safe for use as a YAML identifier by removing -, _, and . characters.
+export function makeSafe(name) {
+  return name.replace(/-/g, '').replace(/_/g, '').replace(/\./g, '');
+}
+
+// Expand a job template string for one package, substituting all known placeholders.
+// {other} is replaced with a tagged sentinel {other:name} for later resolution.
+export function expandJobTemplate(template, { name, safe, packageName, fullName, jobRoot }) {
+  return template
+    .replace(/{other}/g, `{other:${name}}`)
+    .replace(/{path}/g, jobRoot)
+    .replace(/{name}/g, name)
+    .replace(/{safe}/g, safe)
+    .replace(/{package}/g, packageName)
+    .replace(/{full}/g, fullName);
+}
+
+// Resolve all {other:name} sentinels in the combined jobs string.
+// Each sentinel is replaced with a comma-separated list of absolute paths to every OTHER package.
+export function resolveOtherPlaceholders(jobs, allNames, cwd) {
+  for (let i = 0; i < allNames.length; i++) {
+    const cnames = allNames.slice();
+    cnames.splice(i, 1);
+    const cnamesStr = cnames.join(`, ${cwd}/`);
+    const rex = new RegExp(`\\{other:${allNames[i]}\\}`, 'g');
+    jobs = jobs.replace(rex, `${cwd}/${cnamesStr}`);
+  }
+  return jobs;
+}
+
+// Substitute variable results into a document template, replacing {varName} placeholders.
+export function applyVarsToDocTemplate(docTemplate, varResults) {
+  let output = docTemplate;
+  for (const { name, text } of varResults) {
+    const rex = new RegExp(`\\{${name}\\}`, 'g');
+    output = output.replace(rex, text);
+  }
+  return output;
+}
+
+// Wrap content in DO NOT EDIT banners.
+export function wrapWithBanner(content) {
+  const line = '#######################################';
+  const donotedit = '### DO NOT EDIT - THIS IS GENERATED ###';
+  return `${line}\n${donotedit}\n${line}\n\n${content}\n\n${line}\n${donotedit}\n${line}`;
+}

package/tests/lib.test.mjs

@@ -0,0 +1,356 @@
+import { describe, it, expect } from '@jest/globals';
+import {
+  MANIFEST_PRIORITY,
+  stripWhitespace,
+  readTomlName,
+  parseManifestName,
+  buildSearchGlobs,
+  groupByFolder,
+  resolvePackageName,
+  makeSafe,
+  expandJobTemplate,
+  resolveOtherPlaceholders,
+  applyVarsToDocTemplate,
+  wrapWithBanner,
+} from '../src/lib.mjs';
+
+// ─── MANIFEST_PRIORITY ────────────────────────────────────────────────────────
+
+describe('MANIFEST_PRIORITY', () => {
+  it('gives package.json the highest priority (0)', () => {
+    expect(MANIFEST_PRIORITY['package.json']).toBe(0);
+  });
+  it('gives version.json second priority (1)', () => {
+    expect(MANIFEST_PRIORITY['version.json']).toBe(1);
+  });
+  it('gives pyproject.toml the lowest defined priority (2)', () => {
+    expect(MANIFEST_PRIORITY['pyproject.toml']).toBe(2);
+  });
+});
+
+// ─── stripWhitespace ─────────────────────────────────────────────────────────
+
+describe('stripWhitespace', () => {
+  it('removes spaces', () => {
+    expect(stripWhitespace('a b c')).toBe('abc');
+  });
+  it('removes newlines', () => {
+    expect(stripWhitespace('a\nb\nc')).toBe('abc');
+  });
+  it('removes carriage returns', () => {
+    expect(stripWhitespace('a\r\nb')).toBe('ab');
+  });
+  it('leaves non-whitespace characters intact', () => {
+    expect(stripWhitespace('hello:world')).toBe('hello:world');
+  });
+});
+
+// ─── readTomlName ─────────────────────────────────────────────────────────────
+
+describe('readTomlName', () => {
+  it('reads name from [project] section', () => {
+    const content = '[project]\nname = "my-tool"\nversion = "1.0.0"\n';
+    expect(readTomlName(content)).toBe('my-tool');
+  });
+
+  it('reads name from [tool.poetry] section', () => {
+    const content = '[tool.poetry]\nname = "my-poetry-pkg"\nversion = "0.1.0"\n';
+    expect(readTomlName(content)).toBe('my-poetry-pkg');
+  });
+
+  it('accepts single-quoted names', () => {
+    const content = "[project]\nname = 'single-quoted'\n";
+    expect(readTomlName(content)).toBe('single-quoted');
+  });
+
+  it('ignores name outside recognized sections', () => {
+    const content = '[build-system]\nname = "ignored"\n';
+    expect(readTomlName(content)).toBeNull();
+  });
+
+  it('stops reading at the next section header', () => {
+    const content = '[project]\nname = "correct"\n[other]\nname = "wrong"\n';
+    expect(readTomlName(content)).toBe('correct');
+  });
+
+  it('skips blank lines and comments', () => {
+    const content = '[project]\n# a comment\n\nname = "pkg"\n';
+    expect(readTomlName(content)).toBe('pkg');
+  });
+
+  it('returns null when no name field exists in a known section', () => {
+    const content = '[project]\nversion = "1.0.0"\n';
+    expect(readTomlName(content)).toBeNull();
+  });
+
+  it('returns null for completely empty content', () => {
+    expect(readTomlName('')).toBeNull();
+  });
+});
+
+// ─── parseManifestName ────────────────────────────────────────────────────────
+
+describe('parseManifestName', () => {
+  it('parses name from JSON content', () => {
+    expect(parseManifestName('{"name":"my-pkg","version":"1.0.0"}', 'json')).toBe('my-pkg');
+  });
+
+  it('returns null for JSON without a name field', () => {
+    expect(parseManifestName('{"version":"1.0.0"}', 'json')).toBeNull();
+  });
+
+  it('parses name from TOML content', () => {
+    expect(parseManifestName('[project]\nname = "my-tool"\n', 'toml')).toBe('my-tool');
+  });
+
+  it('returns null for invalid JSON', () => {
+    expect(parseManifestName('not valid json', 'json')).toBeNull();
+  });
+
+  it('returns null for TOML with no recognized section', () => {
+    expect(parseManifestName('[build-system]\nname = "x"\n', 'toml')).toBeNull();
+  });
+});
+
+// ─── buildSearchGlobs ─────────────────────────────────────────────────────────
+
+describe('buildSearchGlobs', () => {
+  it('includes all three manifest patterns', () => {
+    const globs = buildSearchGlobs([]);
+    expect(globs).toContain('./**/package.json');
+    expect(globs).toContain('./**/version.json');
+    expect(globs).toContain('./**/pyproject.toml');
+  });
+
+  it('always excludes node_modules', () => {
+    expect(buildSearchGlobs([])).toContain('!**/node_modules');
+  });
+
+  it('adds negation globs for each excluded folder', () => {
+    const globs = buildSearchGlobs(['legacy', 'temp']);
+    expect(globs).toContain('!**/legacy');
+    expect(globs).toContain('!**/temp');
+  });
+
+  it('places exclude entries after the include patterns', () => {
+    const globs = buildSearchGlobs(['skip-me']);
+    const firstInclude = globs.indexOf('./**/package.json');
+    const excludeIdx = globs.indexOf('!**/skip-me');
+    expect(firstInclude).toBeLessThan(excludeIdx);
+  });
+
+  it('returns only include + node_modules exclusion when exclude list is empty', () => {
+    const globs = buildSearchGlobs([]);
+    expect(globs.filter(g => g.startsWith('!') && g !== '!**/node_modules')).toHaveLength(0);
+  });
+});
+
+// ─── groupByFolder ────────────────────────────────────────────────────────────
+
+describe('groupByFolder', () => {
+  it('returns an empty object for empty input', () => {
+    expect(groupByFolder([])).toEqual({});
+  });
+
+  it('groups a single manifest file correctly', () => {
+    const result = groupByFolder(['pkg-a/package.json']);
+    expect(result['pkg-a'].filePath).toBe('pkg-a/package.json');
+  });
+
+  it('picks package.json over version.json (higher priority)', () => {
+    const result = groupByFolder(['pkg-a/version.json', 'pkg-a/package.json']);
+    expect(result['pkg-a'].filePath).toBe('pkg-a/package.json');
+  });
+
+  it('picks package.json over pyproject.toml', () => {
+    const result = groupByFolder(['pkg-a/pyproject.toml', 'pkg-a/package.json']);
+    expect(result['pkg-a'].filePath).toBe('pkg-a/package.json');
+  });
+
+  it('picks version.json over pyproject.toml', () => {
+    const result = groupByFolder(['pkg-b/pyproject.toml', 'pkg-b/version.json']);
+    expect(result['pkg-b'].filePath).toBe('pkg-b/version.json');
+  });
+
+  it('keeps each folder as a separate key', () => {
+    const files = ['pkg-a/package.json', 'pkg-b/package.json', 'pkg-c/pyproject.toml'];
+    const result = groupByFolder(files);
+    expect(Object.keys(result).sort()).toEqual(['pkg-a', 'pkg-b', 'pkg-c']);
+  });
+
+  it('stores the priority value alongside the filePath', () => {
+    const result = groupByFolder(['pkg-a/version.json']);
+    expect(result['pkg-a'].priority).toBe(1);
+  });
+});
+
+// ─── resolvePackageName ───────────────────────────────────────────────────────
+
+describe('resolvePackageName', () => {
+  it('strips the scope prefix from a scoped package name', () => {
+    expect(resolvePackageName('@acme/my-lib')).toBe('my-lib');
+  });
+
+  it('returns unscoped names unchanged', () => {
+    expect(resolvePackageName('my-lib')).toBe('my-lib');
+  });
+
+  it('works with arbitrary scope names', () => {
+    expect(resolvePackageName('@org/pkg-name')).toBe('pkg-name');
+  });
+});
+
+// ─── makeSafe ─────────────────────────────────────────────────────────────────
+
+describe('makeSafe', () => {
+  it('removes dashes', () => {
+    expect(makeSafe('my-component')).toBe('mycomponent');
+  });
+
+  it('removes underscores', () => {
+    expect(makeSafe('my_lib')).toBe('mylib');
+  });
+
+  it('removes dots', () => {
+    expect(makeSafe('my.tool')).toBe('mytool');
+  });
+
+  it('removes all three special characters together', () => {
+    expect(makeSafe('my-lib_v1.0')).toBe('mylibv10');
+  });
+
+  it('leaves alphanumeric characters untouched', () => {
+    expect(makeSafe('mylib123')).toBe('mylib123');
+  });
+});
+
+// ─── expandJobTemplate ────────────────────────────────────────────────────────
+
+describe('expandJobTemplate', () => {
+  const params = {
+    name: 'my-lib',
+    safe: 'mylib',
+    packageName: 'my-lib',
+    fullName: '@acme/my-lib',
+    jobRoot: 'packages',
+  };
+
+  it('replaces {name}', () => {
+    expect(expandJobTemplate('{name}', params)).toBe('my-lib');
+  });
+
+  it('replaces {safe}', () => {
+    expect(expandJobTemplate('{safe}', params)).toBe('mylib');
+  });
+
+  it('replaces {package}', () => {
+    expect(expandJobTemplate('{package}', params)).toBe('my-lib');
+  });
+
+  it('replaces {full}', () => {
+    expect(expandJobTemplate('{full}', params)).toBe('@acme/my-lib');
+  });
+
+  it('replaces {path}', () => {
+    expect(expandJobTemplate('{path}', params)).toBe('packages');
+  });
+
+  it('converts {other} to a tagged sentinel for later resolution', () => {
+    expect(expandJobTemplate('{other}', params)).toBe('{other:my-lib}');
+  });
+
+  it('replaces multiple occurrences of the same placeholder', () => {
+    expect(expandJobTemplate('{name} {name}', params)).toBe('my-lib my-lib');
+  });
+
+  it('replaces all placeholders in a realistic template', () => {
+    const tmpl = '- job: build_{safe}\n  displayName: Build {name}\n  steps:\n    - script: pnpm --filter {full} build';
+    const result = expandJobTemplate(tmpl, params);
+    expect(result).toBe('- job: build_mylib\n  displayName: Build my-lib\n  steps:\n    - script: pnpm --filter @acme/my-lib build');
+  });
+});
+
+// ─── resolveOtherPlaceholders ─────────────────────────────────────────────────
+
+describe('resolveOtherPlaceholders', () => {
+  it('replaces {other:name} with the absolute paths of all other packages', () => {
+    const jobs = 'a:{other:pkg-a}\nb:{other:pkg-b}';
+    const result = resolveOtherPlaceholders(jobs, ['pkg-a', 'pkg-b'], '/root');
+    expect(result).toBe('a:/root/pkg-b\nb:/root/pkg-a');
+  });
+
+  it('lists all other packages in a three-package scenario', () => {
+    const jobs = '{other:pkg-a}';
+    const result = resolveOtherPlaceholders(jobs, ['pkg-a', 'pkg-b', 'pkg-c'], '/root');
+    expect(result).toContain('pkg-b');
+    expect(result).toContain('pkg-c');
+    expect(result).not.toContain('{other:');
+  });
+
+  it('does not include the current package in its own {other} expansion', () => {
+    const jobs = '{other:pkg-a}';
+    const result = resolveOtherPlaceholders(jobs, ['pkg-a', 'pkg-b'], '/root');
+    // The line for pkg-a should reference pkg-b but not pkg-a
+    expect(result).toBe('/root/pkg-b');
+  });
+
+  it('leaves jobs unchanged when there are no {other:*} sentinels', () => {
+    const jobs = 'no sentinels here';
+    expect(resolveOtherPlaceholders(jobs, ['pkg-a', 'pkg-b'], '/root')).toBe('no sentinels here');
+  });
+});
+
+// ─── applyVarsToDocTemplate ───────────────────────────────────────────────────
+
+describe('applyVarsToDocTemplate', () => {
+  it('replaces a single named placeholder', () => {
+    const doc = 'jobs:\n  {jobs}';
+    const result = applyVarsToDocTemplate(doc, [{ name: 'jobs', text: '- job: build' }]);
+    expect(result).toBe('jobs:\n  - job: build');
+  });
+
+  it('replaces multiple named placeholders', () => {
+    const doc = '{a} and {b}';
+    const result = applyVarsToDocTemplate(doc, [
+      { name: 'a', text: 'AAA' },
+      { name: 'b', text: 'BBB' },
+    ]);
+    expect(result).toBe('AAA and BBB');
+  });
+
+  it('replaces multiple occurrences of the same placeholder', () => {
+    const doc = '{jobs}\n---\n{jobs}';
+    const result = applyVarsToDocTemplate(doc, [{ name: 'jobs', text: 'X' }]);
+    expect(result).toBe('X\n---\nX');
+  });
+
+  it('returns the template unchanged when varResults is empty', () => {
+    const doc = 'no placeholders';
+    expect(applyVarsToDocTemplate(doc, [])).toBe('no placeholders');
+  });
+});
+
+// ─── wrapWithBanner ───────────────────────────────────────────────────────────
+
+describe('wrapWithBanner', () => {
+  it('starts and ends with the banner line', () => {
+    const result = wrapWithBanner('content');
+    expect(result.startsWith('#######################################')).toBe(true);
+    expect(result.endsWith('#######################################')).toBe(true);
+  });
+
+  it('contains the DO NOT EDIT text', () => {
+    const result = wrapWithBanner('content');
+    expect(result).toContain('DO NOT EDIT - THIS IS GENERATED');
+  });
+
+  it('preserves the original content', () => {
+    const result = wrapWithBanner('my yaml content');
+    expect(result).toContain('my yaml content');
+  });
+
+  it('wraps content with a blank line on each side', () => {
+    const result = wrapWithBanner('body');
+    expect(result).toContain('\n\nbody\n\n');
+  });
+});

package/tests/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "@acme/my-component",
+  "version": "1.0.0"
+}

package/tests/pyproject.toml

@@ -0,0 +1,5 @@
+[project]
+name = "my-python-tool"
+version = "0.1.0"
+description = "A sample Python tool"
+authors = [{ name = "Maintainer", email = "maintainer@example.com" }]

package/tests/version.json

@@ -0,0 +1,4 @@
+{
+  "name": "@acme/my-lib",
+  "version": "2.0.0"
+}

package/index.js

@@ -1,167 +0,0 @@
-#!/usr/bin/env node
-import * as url from 'url';
-import path from 'path';
-import { globby } from 'globby';
-import { readFileSync, writeFileSync, existsSync } from "fs";
-
-const __dirname = url.fileURLToPath(new URL('.', import.meta.url));
-
-function stripIt(ins) {
-  return ins.replace(/( |\r\n|\n|\r)/gm,"");
-}
-
-async function main(options) {
-    var configFile = path.join(__dirname, options.config);
-    const try1 = configFile;
-
-    if(!existsSync(configFile)) {
-        configFile = path.join(options.config);
-    }
-
-    if(!existsSync(configFile)) {
-       throw `enablement-build-template-generate: could not load config file ${configFile}, also tried ${try1}`;
-    }
-
-    const templatePath = path.dirname(configFile);
-
-    const config = JSON.parse(readFileSync(configFile,'utf8'));
-
-    const plist = [];
-
-    let search = options.exclude;
-    if(search.length) {
-        for(let i=0;i<search.length;i++) {
-            search[i]='!**/'+search[i];
-        }
-    }
-    search.unshift(`./**/package.json`);
-    search.push(`!**/node_modules`);
-
-    Object.keys(config).forEach((templateFilename)=>{
-
-        plist.push(new Promise(async (primaryResolve, reject) => {
-
-            const docTemplate = readFileSync(path.join(templatePath, templateFilename), "utf8");
-            const jlist = [];
-            Object.keys(config[templateFilename]).forEach((varname)=>{
-                const jobConfig = config[templateFilename][varname];
-                const job = new Promise(async (resolve, reject) => {
-                    const jobTemplate = readFileSync(path.join(templatePath, jobConfig.template), "utf8");
-                    const cwd = path.join(templatePath, jobConfig.rootPath);
-
-                    let jobRoot = jobConfig.rootPath.replace(/^[\.\/\\]+/, '');
-
-
-                    console.log(search);
-
-                    globby(search,{ cwd: cwd }).then((images)=>{
-                        images.sort();
-                        let jobs = [];
-                        let exclude = jobConfig.exclude||[];
-                        const allNames = [];
-
-                        for (let i = 0; i < images.length; i++) {
-                            let name = images[i].replace(/\/package\.json/g, '');
-                            allNames.push(name);
-                            if(name.startsWith("_")) continue;
-
-                            const packageJson = JSON.parse(readFileSync(path.join(cwd,images[i]),'utf8'));
-                            let fullName = packageJson.name;
-                            let packageName = packageJson.name;
-                            if(packageName.startsWith('@')) {
-                                packageName = packageName.split("\/")[1];
-                            }
-
-                            let job = jobTemplate;
-                            if(exclude.indexOf(name)>=0) continue;
-                            let safe = name.replace(/-/g, '').replace(/_/g, '').replace(/\./g, '');
-                            job = job.replace(/{other}/g, `{other:${name}}`).replace(/{path}/g,jobRoot).replace(/{name}/g, name).replace(/{safe}/g, safe).replace(/{package}/g, packageName).replace(/{full}/g, fullName);
-                            jobs.push(job);
-                        }
-
-                        jobs = jobs.join('\n');
-                        for (let i = 0; i < allNames.length; i++) {
-                            let cnames = allNames.slice();
-                            cnames.splice(i,1);
-                            cnames = cnames.join(`, ${cwd}/`);
-                            let rex = `{other:${allNames[i]}}`;
-                            rex=new RegExp(rex,'g');
-                            jobs = jobs.replace(rex, `${cwd}/${cnames}`);
-                        }
-
-                        resolve({name:varname, text:jobs});
-                    },reject);
-
-                });
-                jlist.push(job);
-            });
-
-            Promise.all(jlist).then((results)=>{
-                var output = docTemplate;
-
-                Object.keys(results).forEach((idx)=>{
-                    const varname = results[idx].name;
-                    let rex = new RegExp('\\{'+varname+'\\}',"g");
-                    output = output.replace(rex, results[idx].text);
-                });
-
-                const line = "#######################################";
-                const donotedit = "### DO NOT EDIT - THIS IS GENERATED ###";
-                output = `${line}\n${donotedit}\n${line}\n\n${output}\n\n${line}\n${donotedit}\n${line}`;
-
-                if(stripIt(output)!==docTemplate) {
-                  const outFile = path.join(templatePath, `../${templateFilename}`);
-                  writeFileSync(path.join(templatePath, `../${templateFilename}`), output, "utf8");
-                }
-
-                primaryResolve(`generated template ${templateFilename}`);
-            },reject);
-        }));
-    })
-
-    return Promise.all(plist);
-}
-
-let options = {
-    config: "./.cicd/templates/templated.json",
-    exclude: [],
-    debug: false,
-    push: true
-}
-
-let argv = process.argv;
-
-for (let i = 2; i < argv.length; i++) {
-    if (argv[i] === "--debug") { options.debug = true; continue; }
-    if (argv[i].substring(0, 2) === "--") {
-        let name = argv[i].substring(2);
-        if (name==="exclude") {
-            options[name] = argv[i + 1].replace(/\s/g,',').split(',');
-            i++;
-        } else if (options[name] !== undefined) {
-            options[name] = argv[i + 1];
-            i++;
-        } else {
-            console.error('Expected a known option');
-            process.exit(1);
-        }
-    }
-}
-
-(async () => {
-    try {
-        console.log('\x1b[32m%s\x1b[0m', "Running enablement-build-template-generate with options:\n", JSON.stringify(options, null, 2));
-        main(options).then((results) => {
-            console.log(results.join('\n'));
-            if (options.debug) console.log("DONE");
-            process.exit(0);
-        }, (e) => {
-            console.log('\x1b[32m%s\x1b[0m',e);
-            if (options.debug) console.log("ERROR");
-            process.exit(1);
-        })
-    } catch (e) {
-        console.log('\x1b[32m%s\x1b[0m',e);
-        process.exit(1);
-    }
-})();