@redpanda-data/docs-extensions-and-macros 5.13.1 → 5.13.2

package/bin/doc-tools-mcp.js

@@ -291,7 +291,7 @@ const tools = [
       properties: {
         output: {
           type: 'string',
-          description: 'Output file path relative to repo root (optional, defaults to "cloud-controlplane/x-topics/cloud-regions.md")'
+          description: 'Output file path relative to repo root; must stay inside the repository (optional, defaults to "cloud-controlplane/x-topics/cloud-regions.md")'
         },
         format: {
           type: 'string',
@@ -316,7 +316,11 @@ const tools = [
         },
         template: {
           type: 'string',
-          description: 'Path to custom Handlebars template relative to repo root (optional)'
+          description: 'Path to custom Handlebars template relative to repo root; must stay inside the repository (optional)'
+        },
+        cluster_type: {
+          type: 'string',
+          description: 'Only include regions/tiers available for this cluster type, usually "BYOC" or "Dedicated"; the CLI validates the value against the cluster types the source data offers and lists them if it does not match (optional, requires output or dry_run)'
         },
         dry_run: {
           type: 'boolean',

package/bin/doc-tools.js

@@ -12,7 +12,7 @@ const path = require('path')
 const fs = require('fs')
 
 // Import extracted utility modules
-const { findRepoRoot, fail, commonOptions } = require('../cli-utils/doc-tools-utils')
+const { findRepoRoot, resolveInsideRepo, fail, commonOptions } = require('../cli-utils/doc-tools-utils')
 const {
   requireTool,
   requireCmd,
@@ -1827,6 +1827,14 @@ automation
  * generates either Markdown or AsciiDoc tables for documentation. Supports custom templates
  * and dry-run mode for previewing output.
  *
+ * A custom template is a Handlebars file inside this repository and receives this context:
+ * `providers`, each with `name` ("GCP"), `displayName` ("Google Cloud Platform (GCP)") and
+ * `regions`, each region with `name`, `zones` (comma separated) and `tiers`; `clusterType`,
+ * the cluster type the data was filtered to, set only with --cluster-type, in which case the
+ * tier entries carry no per-tier cluster type; and `lastUpdated`, an ISO timestamp. The
+ * bundled templates in tools/cloud-regions show all of it in use. The template decides the
+ * markup, so with --template the --format value is only checked for validity.
+ *
  * @why
  * Cloud region data changes frequently as new regions are added and tier availability evolves.
  * The cloudv2-infra repository contains the source of truth for cloud infrastructure. Manual
@@ -1852,6 +1860,12 @@ automation
  * npx doc-tools generate cloud-regions \
  *   --output custom/path/regions.md
  *
+ * # Generate an AsciiDoc partial for one cluster type with a custom template
+ * export GITHUB_TOKEN=ghp_xxx
+ * npx doc-tools generate cloud-regions --format adoc --cluster-type BYOC \
+ *   --template docs-data/templates/cloud-regions.hbs \
+ *   --output modules/reference/partials/generated/regions-byoc.adoc
+ *
  * # Use different branch for testing
  * export GITHUB_TOKEN=ghp_xxx
  * npx doc-tools generate cloud-regions --ref staging
@@ -1864,32 +1878,44 @@ automation
 automation
   .command('cloud-regions')
   .description('Generate Markdown table of cloud regions and tiers from GitHub YAML file')
-  .option('--output <file>', 'Output file (relative to repo root)', 'cloud-controlplane/x-topics/cloud-regions.md')
+  .option('--output <file>', 'Output file (relative to repo root, must stay inside the repository)', 'cloud-controlplane/x-topics/cloud-regions.md')
   .option('--format <fmt>', 'Output format: md (Markdown) or adoc (AsciiDoc)', 'md')
   .option('--owner <owner>', 'GitHub repository owner', 'redpanda-data')
   .option('--repo <repo>', 'GitHub repository name', 'cloudv2-infra')
   .option('--path <path>', 'Path to YAML file in repository', 'apps/master-data-reconciler/manifests/overlays/production/master-data.yaml')
   .option('--ref <ref>', 'Git reference (branch, tag, or commit SHA)', 'integration')
-  .option('--template <path>', 'Path to custom Handlebars template (relative to repo root)')
+  .option('--template <path>', 'Path to custom Handlebars template (relative to repo root, must stay inside the repository)')
+  .option('--cluster-type <type>', 'Only include regions/tiers available for this cluster type, such as BYOC or Dedicated (requires --output or --dry-run)')
   .option('--dry-run', 'Print output to stdout instead of writing file')
-  .action(async (options) => {
+  .action(async (options, command) => {
     const { generateCloudRegions } = require('../tools/cloud-regions/generate-cloud-regions.js')
     const { getGitHubToken } = require('../cli-utils/github-token')
 
     try {
+      // The default output path holds the unfiltered table, so a filtered run
+      // that forgets --output silently replaces it, and the documented
+      // BYOC-then-Dedicated pair would leave only whichever ran last.
+      if (options.clusterType && !options.dryRun && command.getOptionValueSource('output') === 'default') {
+        throw new Error('--cluster-type needs its own destination: pass --output <file> for the filtered table, or --dry-run to preview it.')
+      }
+      // Contain every caller-supplied path before doing any work: both options
+      // are also reachable through the MCP server, so --template must not read
+      // and --output must not write outside the repository.
+      const repoRoot = findRepoRoot()
+      const templatePath = options.template
+        ? resolveInsideRepo(repoRoot, options.template, '--template')
+        : undefined
+      if (templatePath && !fs.existsSync(templatePath)) {
+        throw new Error(`Custom template not found: ${templatePath}`)
+      }
+      const absOutput = options.dryRun
+        ? undefined
+        : resolveInsideRepo(repoRoot, options.output, '--output')
       const token = getGitHubToken()
       if (!token) {
         throw new Error('GitHub token is required to fetch from private cloudv2-infra repo.')
       }
       const fmt = (options.format || 'md').toLowerCase()
-      let templatePath
-      if (options.template) {
-        const repoRoot = findRepoRoot()
-        templatePath = path.resolve(repoRoot, options.template)
-        if (!fs.existsSync(templatePath)) {
-          throw new Error(`Custom template not found: ${templatePath}`)
-        }
-      }
       const out = await generateCloudRegions({
         owner: options.owner,
         repo: options.repo,
@@ -1897,14 +1923,13 @@ automation
         ref: options.ref,
         format: fmt,
         token,
-        template: templatePath
+        template: templatePath,
+        clusterType: options.clusterType
       })
       if (options.dryRun) {
         process.stdout.write(out)
         console.log(`\nDone: (dry-run) ${fmt === 'adoc' ? 'AsciiDoc' : 'Markdown'} output printed to stdout.`)
       } else {
-        const repoRoot = findRepoRoot()
-        const absOutput = path.resolve(repoRoot, options.output)
         fs.mkdirSync(path.dirname(absOutput), { recursive: true })
         fs.writeFileSync(absOutput, out, 'utf8')
         console.log(`Done: Wrote ${absOutput}`)

package/bin/mcp-tools/cloud-regions.js

@@ -9,13 +9,14 @@ const { getAntoraStructure } = require('./antora');
 /**
  * Generate cloud regions table documentation
  * @param {Object} args - Arguments
- * @param {string} [args.output] - Output file path (relative to repo root)
+ * @param {string} [args.output] - Output file path (relative to repo root, must stay inside the repository)
  * @param {string} [args.format] - Output format: 'md' or 'adoc'
  * @param {string} [args.owner] - GitHub repository owner
  * @param {string} [args.repo] - GitHub repository name
  * @param {string} [args.path] - Path to YAML file in repository
  * @param {string} [args.ref] - Git reference (branch, tag, or commit SHA)
- * @param {string} [args.template] - Path to custom Handlebars template
+ * @param {string} [args.template] - Path to custom Handlebars template (relative to repo root, must stay inside the repository)
+ * @param {string} [args.cluster_type] - Only include regions/tiers available for this cluster type ('BYOC' or 'Dedicated')
  * @param {boolean} [args.dry_run] - Print output to stdout instead of writing file
  * @returns {Object} Generation results
  */
@@ -73,6 +74,11 @@ function generateCloudRegions(args = {}) {
       baseArgs.push(args.template);
     }
 
+    if (args.cluster_type) {
+      baseArgs.push('--cluster-type');
+      baseArgs.push(args.cluster_type);
+    }
+
     if (args.dry_run) {
       baseArgs.push('--dry-run');
     }

package/cli-utils/doc-tools-utils.js

@@ -28,6 +28,59 @@ function findRepoRoot (start = process.cwd()) {
   process.exit(1)
 }
 
+/**
+ * Returns the canonical path with symlinks resolved, or the input unchanged when
+ * the path cannot be resolved (for example, it does not exist).
+ *
+ * @param {string} target - The path to canonicalize.
+ * @returns {string} The canonical path, or `target` if it cannot be resolved.
+ */
+function realPathOrSelf (target) {
+  try {
+    return fs.realpathSync(target)
+  } catch (err) {
+    return target
+  }
+}
+
+/**
+ * Resolves a caller-supplied path against the repository root and refuses any
+ * path that escapes it.
+ *
+ * Options such as `--template` and `--output` are resolved with
+ * `path.resolve(repoRoot, value)`, which silently keeps an absolute path as-is
+ * and lets `../` climb out of the repository. Both are reachable from the MCP
+ * server, where the value comes from an agent rather than from the person at the
+ * keyboard, so a read option turns into a file-disclosure primitive and a write
+ * option into a write-anywhere primitive. Use this helper for every path option
+ * that names a file the CLI then reads or writes.
+ *
+ * Symlinks are resolved on the deepest existing part of the target, so a symlink
+ * inside the repository cannot be used to point outside it. The part that does
+ * not exist yet (a `--output` file that is about to be created) is checked
+ * lexically, after `path.resolve` has already collapsed any `..` segments.
+ *
+ * @param {string} repoRoot - Absolute path to the repository root.
+ * @param {string} userPath - The caller-supplied path, absolute or relative to the repo root.
+ * @param {string} [label] - Human-readable name of the option, used in the error message.
+ * @returns {string} The absolute, contained path.
+ * @throws {Error} If the resolved path is outside the repository root.
+ */
+function resolveInsideRepo (repoRoot, userPath, label = 'path') {
+  const resolved = path.resolve(repoRoot, userPath)
+  const root = realPathOrSelf(repoRoot)
+  let existing = resolved
+  while (!fs.existsSync(existing) && path.dirname(existing) !== existing) {
+    existing = path.dirname(existing)
+  }
+  const real = path.join(realPathOrSelf(existing), path.relative(existing, resolved))
+  const relative = path.relative(root, real)
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`${label} must be inside the repository (${repoRoot}): ${userPath}`)
+  }
+  return resolved
+}
+
 /**
  * Prints an error message to stderr and exits the process with a non-zero status.
  *
@@ -49,6 +102,7 @@ const commonOptions = {
 
 module.exports = {
   findRepoRoot,
+  resolveInsideRepo,
   fail,
   commonOptions
 }

package/mcp/CLI_INTERFACE.adoc

@@ -203,13 +203,14 @@ npx doc-tools generate cloud-regions [options]
 
 *Optional flags:*
 
---output:: Output file path
---format:: Output format (json, yaml, adoc)
+--output:: Output file path, relative to repo root and inside the repository
+--format:: Output format (md, adoc)
 --owner:: GitHub repository owner
 --repo:: GitHub repository name
 --path:: Path to regions file in repository
 --ref:: Git reference (branch, tag, commit)
---template:: AsciiDoc template file
+--template:: Handlebars template file, relative to repo root and inside the repository. The template decides the markup, so `--format` is then only checked for validity
+--cluster-type:: Only include regions and tiers available for one cluster type, such as BYOC or Dedicated. Requires `--output` or `--dry-run`
 --dry-run:: Show what would be generated without writing files
 
 === crd-spec

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.13.1",
+  "version": "5.13.2",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",

package/tools/cloud-regions/cloud-regions-table-adoc.hbs

@@ -11,7 +11,7 @@ For source code and documentation:
 - Docs: https://redpandadata.atlassian.net/wiki/spaces/DOC/pages/1185054748/Doc+Tools+CLI
 ////
 
-Usage tiers define the sizing of a cluster and provide tested and guaranteed workload configurations for throughput, logical partitions, and connections. Availability depends on the region and the cluster type (BYOC, Dedicated). See link:https://docs.redpanda.com/redpanda-cloud/reference/tiers/byoc-tiers/[BYOC tiers] and link:https://docs.redpanda.com/redpanda-cloud/reference/tiers/dedicated-tiers/[Dedicated tiers] for further details.
+Usage tiers define the sizing of a cluster and provide tested and guaranteed workload configurations for throughput, logical partitions, and connections. Availability depends on the region{{#if clusterType}}. This table lists only the tiers available for {{clusterType}} clusters{{else}} and the cluster type (BYOC, Dedicated){{/if}}. See link:https://docs.redpanda.com/redpanda-cloud/reference/tiers/byoc-tiers/[BYOC tiers] and link:https://docs.redpanda.com/redpanda-cloud/reference/tiers/dedicated-tiers/[Dedicated tiers] for further details.
 
 {{!--{{#if lastUpdated}}
 _Last Updated: {{lastUpdated}}_

package/tools/cloud-regions/cloud-regions-table-md.hbs

@@ -11,7 +11,7 @@ For source code and documentation:
 - Docs: https://redpandadata.atlassian.net/wiki/spaces/DOC/pages/1185054748/Doc+Tools+CLI
 -->
 
-Usage tiers define the sizing of a cluster and provide tested and guaranteed workload configurations for throughput, logical partitions, and connections. Availability depends on the region and the cluster type (BYOC, Dedicated). See [BYOC tiers](https://docs.redpanda.com/redpanda-cloud/reference/tiers/byoc-tiers/) and [Dedicated tiers](https://docs.redpanda.com/redpanda-cloud/reference/tiers/dedicated-tiers/) for further details.
+Usage tiers define the sizing of a cluster and provide tested and guaranteed workload configurations for throughput, logical partitions, and connections. Availability depends on the region{{#if clusterType}}. This table lists only the tiers available for {{clusterType}} clusters{{else}} and the cluster type (BYOC, Dedicated){{/if}}. See [BYOC tiers](https://docs.redpanda.com/redpanda-cloud/reference/tiers/byoc-tiers/) and [Dedicated tiers](https://docs.redpanda.com/redpanda-cloud/reference/tiers/dedicated-tiers/) for further details.
 
 {{!--{{#if lastUpdated}}
 <p><em>Last Updated: {{lastUpdated}}</em></p>

package/tools/cloud-regions/generate-cloud-regions.js

@@ -40,18 +40,38 @@ const providerMap = {
   CLOUD_PROVIDER_AZURE: 'Azure',
 };
 const providerOrder = ['GCP', 'AWS', 'Azure'];
+const providerDisplayNames = {
+  GCP: 'Google Cloud Platform (GCP)',
+  AWS: 'Amazon Web Services (AWS)',
+  Azure: 'Azure',
+};
 const clusterTypeMap = {
   CLUSTER_TYPE_BYOC: 'BYOC',
   CLUSTER_TYPE_DEDICATED: 'Dedicated',
   CLUSTER_TYPE_FMC: 'Dedicated',
 };
+// Warn once per unmapped cluster type per process, so a rename upstream is loud
+// instead of being spread over every region row.
+const warnedClusterTypes = new Set();
+
 /**
  * Returns the display name for a given cluster type, or the original value if unmapped.
+ *
+ * An unmapped value is a signal, not a detail: it reaches the published table
+ * verbatim, and if a mapped enum is ever renamed upstream the table it feeds
+ * (every Dedicated region comes from CLUSTER_TYPE_FMC) empties out quietly. Warn
+ * so that shows up in the generation logs.
+ *
  * @param {string} ct - The internal cluster type identifier.
  * @return {string} The display name for the cluster type.
  */
 function displayClusterType(ct) {
-  return clusterTypeMap[ct] || ct;
+  if (clusterTypeMap[ct]) return clusterTypeMap[ct];
+  if (!warnedClusterTypes.has(ct)) {
+    warnedClusterTypes.add(ct);
+    console.warn(`[cloud-regions] WARN: Unmapped cluster type '${ct}'. It appears in the table exactly as written here, and --cluster-type has to be given that same value. Add it to clusterTypeMap to give it a display name.`);
+  }
+  return ct;
 }
 
 /**
@@ -105,15 +125,42 @@ async function fetchYaml({ owner, repo, path, ref = 'main', token }) {
 }
 
 /**
- * Parses YAML text describing cloud regions and products, filters for public products, and organizes regions by provider.
+ * Collects every cluster type display name that the source data offers on a
+ * public tier, together with the ones this tool maps by default.
  *
- * The function expects YAML content with a top-level `regions` array and an optional `products` array. It groups regions by cloud provider, includes only those with at least one public product tier, and formats tier and cluster type information for each region. Providers and regions without public tiers are excluded from the result.
+ * @param {Array<Object>} regions - The `regions` array from the source YAML.
+ * @param {Set<string>} publicProductNames - Names of products marked public.
+ * @return {Set<string>} Cluster type display names available for filtering.
+ */
+function collectClusterTypes(regions, publicProductNames) {
+  const available = new Set(Object.values(clusterTypeMap));
+  for (const region of regions) {
+    const availability = region.redpandaProductAvailability;
+    if (!availability || typeof availability !== 'object') continue;
+    for (const tier of Object.values(availability)) {
+      if (!tier.redpandaProductName || !publicProductNames.has(tier.redpandaProductName)) continue;
+      if (!Array.isArray(tier.clusterTypes)) continue;
+      for (const ct of tier.clusterTypes) available.add(displayClusterType(ct));
+    }
+  }
+  return available;
+}
+
+/**
+ * Parses YAML text describing cloud regions and products and returns both the
+ * providers and the cluster type the result was filtered to.
+ *
+ * Templates need the resolved cluster type, not the string the caller typed, so
+ * that a filtered table can name it in a heading or an intro. Keeping the
+ * resolution here means the YAML is parsed once.
  *
  * @param {string} yamlText - The YAML content to parse and process.
- * @return {Array<Object>} An array of provider objects, each containing a name and a list of regions with their available public product tiers.
- * @throws {Error} If the YAML is malformed or missing the required `regions` array.
+ * @param {Object} [options] - Processing options.
+ * @param {string} [options.clusterType] - Optional cluster type display name (case-insensitive).
+ * @return {{providers: Array<Object>, clusterType: string|undefined}} The providers and the resolved cluster type filter.
+ * @throws {Error} If the YAML is malformed, missing the required `regions` array, or the cluster type is unsupported.
  */
-function processCloudRegions(yamlText) {
+function buildCloudRegions(yamlText, { clusterType } = {}) {
   let data;
   try {
     data = jsYaml.load(yamlText);
@@ -146,13 +193,33 @@ function processCloudRegions(yamlText) {
   } else {
     console.warn('[cloud-regions] WARN: No products array found in YAML.');
   }
+  // Accept any cluster type the source data actually offers, not only the ones
+  // clusterTypeMap knows about: an unmapped type such as CLUSTER_TYPE_SERVERLESS
+  // already shows up verbatim in the unfiltered table, so refusing to filter on
+  // it would be inconsistent with the output.
+  let clusterTypeFilter;
+  if (clusterType) {
+    const validClusterTypes = [...collectClusterTypes(data.regions, publicProductNames)].sort();
+    const wanted = String(clusterType).trim().toLowerCase();
+    clusterTypeFilter = validClusterTypes.find((ct) => ct.toLowerCase() === wanted);
+    if (!clusterTypeFilter) {
+      throw new Error(`Unsupported cluster type: ${clusterType}. Use one of: ${validClusterTypes.join(', ')}.`);
+    }
+  }
   // Prepare providers array for template, only including public products and using name
   const providers = providerOrder
     .filter((prov) => grouped[prov] && grouped[prov].length > 0)
     .map((prov) => {
       // Only include regions that have at least one public product/tier
       const filteredRegions = grouped[prov].map((region) => {
-        const zones = Array.isArray(region.zones) ? region.zones.join(',') : (region.zones || '');
+        // Sort so a pure reordering upstream cannot produce a docs diff, and join
+        // with ', ' so long zone lists can wrap inside table cells.
+        const zones = Array.isArray(region.zones)
+          ? [...region.zones]
+            .map(String)
+            .sort((a, b) => a.localeCompare(b, 'en', { numeric: true }))
+            .join(', ')
+          : (region.zones || '');
         let tiers = [];
         if (region.redpandaProductAvailability && typeof region.redpandaProductAvailability === 'object') {
           // Group by tier name, collect all cluster types for that tier
@@ -161,14 +228,22 @@ function processCloudRegions(yamlText) {
             if (!t.redpandaProductName || !publicProductNames.has(t.redpandaProductName)) {
               continue;
             }
+            let displayTypes = Array.isArray(t.clusterTypes) ? t.clusterTypes.map(displayClusterType) : [];
+            if (clusterTypeFilter) {
+              displayTypes = displayTypes.filter((ct) => ct === clusterTypeFilter);
+              if (displayTypes.length === 0) continue;
+            }
             const productName = t.redpandaProductName;
             if (!tierMap[productName]) tierMap[productName] = new Set();
-            if (Array.isArray(t.clusterTypes)) {
-              for (const ct of t.clusterTypes) tierMap[productName].add(displayClusterType(ct));
-            }
+            for (const ct of displayTypes) tierMap[productName].add(ct);
           }
           tiers = Object.entries(tierMap)
-            .map(([productName, cts]) => `${productName}: ${Array.from(cts).sort().join(', ')}`)
+            // With a filter every tier carries exactly the filtered type, so
+            // repeating it on all 50-odd rows is noise: the template says it
+            // once from clusterType instead.
+            .map(([productName, cts]) => (clusterTypeFilter
+              ? productName
+              : `${productName}: ${Array.from(cts).sort().join(', ')}`))
             .sort((a, b) => a.localeCompare(b));
         }
         return {
@@ -178,10 +253,12 @@ function processCloudRegions(yamlText) {
         };
       }).filter(region => region.tiers && region.tiers.length > 0);
       if (filteredRegions.length === 0) {
-        console.info(`[cloud-regions] INFO: No public tiers found for provider '${prov}'.`);
+        const because = clusterTypeFilter ? ` available for ${clusterTypeFilter} clusters` : '';
+        console.info(`[cloud-regions] INFO: No public tiers${because} found for provider '${prov}'.`);
       }
       return {
         name: prov,
+        displayName: providerDisplayNames[prov] || prov,
         regions: filteredRegions,
       };
     })
@@ -189,7 +266,22 @@ function processCloudRegions(yamlText) {
   if (providers.length === 0) {
     console.warn('[cloud-regions] WARN: No providers/regions found after filtering.');
   }
-  return providers;
+  return { providers, clusterType: clusterTypeFilter };
+}
+
+/**
+ * Parses YAML text describing cloud regions and products, filters for public products, and organizes regions by provider.
+ *
+ * The function expects YAML content with a top-level `regions` array and an optional `products` array. It groups regions by cloud provider, includes only those with at least one public product tier, and formats tier and cluster type information for each region. Providers and regions without public tiers are excluded from the result.
+ *
+ * @param {string} yamlText - The YAML content to parse and process.
+ * @param {Object} [options] - Processing options.
+ * @param {string} [options.clusterType] - Optional cluster type display name ('BYOC' or 'Dedicated', case-insensitive). When set, only tiers available for that cluster type are included, and regions with no matching tiers are dropped.
+ * @return {Array<Object>} An array of provider objects, each containing a name and a list of regions with their available public product tiers.
+ * @throws {Error} If the YAML is malformed or missing the required `regions` array.
+ */
+function processCloudRegions(yamlText, options = {}) {
+  return buildCloudRegions(yamlText, options).providers;
 }
 
 /**
@@ -206,10 +298,11 @@ function processCloudRegions(yamlText) {
  * @param {string} [options.format='md'] - The output format (for example, 'md' for Markdown).
  * @param {string} [options.token] - Optional GitHub token for authentication.
  * @param {string} [options.template] - Optional path to custom Handlebars template.
+ * @param {string} [options.clusterType] - Optional cluster type filter ('BYOC' or 'Dedicated', case-insensitive).
  * @returns {string} The rendered cloud regions output.
  * @throws {Error} If fetching, processing, or rendering fails, or if no valid providers or regions are found.
  */
-async function generateCloudRegions({ owner, repo, path, ref = 'main', format = 'md', token, template }) {
+async function generateCloudRegions({ owner, repo, path, ref = 'main', format = 'md', token, template, clusterType }) {
   let yamlText;
   try {
     yamlText = await fetchYaml({ owner, repo, path, ref, token });
@@ -218,8 +311,9 @@ async function generateCloudRegions({ owner, repo, path, ref = 'main', format =
     throw err;
   }
   let providers;
+  let resolvedClusterType;
   try {
-    providers = processCloudRegions(yamlText);
+    ({ providers, clusterType: resolvedClusterType } = buildCloudRegions(yamlText, { clusterType }));
   } catch (err) {
     console.error(`[cloud-regions] ERROR: Failed to process cloud regions: ${err.message}`);
     throw err;
@@ -230,7 +324,7 @@ async function generateCloudRegions({ owner, repo, path, ref = 'main', format =
   }
   const lastUpdated = new Date().toISOString();
   try {
-    return renderCloudRegions({ providers, format, lastUpdated, template });
+    return renderCloudRegions({ providers, format, lastUpdated, template, clusterType: resolvedClusterType });
   } catch (err) {
     console.error(`[cloud-regions] ERROR: Failed to render cloud regions: ${err.message}`);
     throw err;

package/tools/cloud-regions/render-cloud-regions.js

@@ -12,10 +12,12 @@ const handlebars = require('handlebars');
  * @param {Array} opts.providers - List of cloud provider objects, each with a name and an array of regions.
  * @param {string} opts.format - Output format, either 'md' (Markdown) or 'adoc' (AsciiDoc).
  * @param {string} [opts.lastUpdated] - Optional ISO timestamp indicating when the data was last updated.
+ * @param {string} [opts.template] - Optional absolute path to a custom Handlebars template. Overrides the bundled template for the given format. The caller is responsible for containing this path: bin/doc-tools.js resolves it with resolveInsideRepo before calling, and that is the single enforcement point for the CLI and the MCP server alike.
+ * @param {string} [opts.clusterType] - Optional cluster type the data was filtered to. Exposed to the template so a filtered table can name it.
  * @returns {string} The rendered output string.
  * @throws {Error} If the providers array is missing or empty.
  */
-function renderCloudRegions({ providers, format, lastUpdated }) {
+function renderCloudRegions({ providers, format, lastUpdated, template, clusterType }) {
   if (!Array.isArray(providers) || providers.length === 0) {
     throw new Error('No providers/regions found in YAML.');
   }
@@ -27,19 +29,23 @@ function renderCloudRegions({ providers, format, lastUpdated }) {
     ...provider,
     regions: [...provider.regions].sort((a, b) => a.name.localeCompare(b.name))
   }));
-  const templateFile = path.join(__dirname, `cloud-regions-table-${format}.hbs`);
+  const templateFile = template || path.join(__dirname, `cloud-regions-table-${format}.hbs`);
   if (!fs.existsSync(templateFile)) {
     throw new Error(`Template file not found: ${templateFile}`);
   }
-  let templateSrc, template;
+  let compiledTemplate;
   try {
-    templateSrc = fs.readFileSync(templateFile, 'utf8');
-    template = handlebars.compile(templateSrc);
+    const templateSrc = fs.readFileSync(templateFile, 'utf8');
+    // compile() only parses on first render, so a syntax error in a custom
+    // template would otherwise be reported as a render failure and send the
+    // author looking at their data instead of their braces. precompile parses now.
+    handlebars.precompile(templateSrc);
+    compiledTemplate = handlebars.compile(templateSrc);
   } catch (err) {
     throw new Error(`Failed to compile Handlebars template at ${templateFile}: ${err.message}`);
   }
   try {
-    return template({ providers: sortedProviders, lastUpdated });
+    return compiledTemplate({ providers: sortedProviders, lastUpdated, clusterType });
   } catch (err) {
     throw new Error(`Failed to render Handlebars template at ${templateFile}: ${err.message}`);
   }