@aifabrix/builder 2.42.1 → 2.44.0

package/lib/utils/environment-scoped-resources.js

@@ -0,0 +1,144 @@
+/**
+ * Environment-scoped resource naming (shared infra: dev/tst on same Postgres/Redis/Docker).
+ * Effective only when user gate AND app flag AND run env is dev|tst.
+ *
+ * @fileoverview environmentScopedResources + useEnvironmentScopedResources helpers
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * Run/env keys that participate in resource prefixing (not pro).
+ * @param {string} envKey - Normalized lowercase env key
+ * @returns {boolean}
+ */
+function isScopedRunEnvironmentKey(envKey) {
+  if (!envKey || typeof envKey !== 'string') return false;
+  const k = envKey.toLowerCase();
+  return k === 'dev' || k === 'tst';
+}
+
+/**
+ * Effective local/deploy prefix behavior: user gate ∧ app flag ∧ dev|tst.
+ *
+ * @param {boolean} useEnvironmentScopedResources - ~/.aifabrix/config.yaml
+ * @param {boolean} appEnvironmentScopedResources - application.yaml
+ * @param {string} runEnvKey - dev | tst | pro | other (lowercase)
+ * @returns {boolean}
+ */
+function computeEffectiveEnvironmentScopedResources(
+  useEnvironmentScopedResources,
+  appEnvironmentScopedResources,
+  runEnvKey
+) {
+  return (
+    Boolean(useEnvironmentScopedResources) &&
+    Boolean(appEnvironmentScopedResources) &&
+    isScopedRunEnvironmentKey(runEnvKey)
+  );
+}
+
+/**
+ * Redis logical DB index when env-scoped resources are effective.
+ * dev → 0, tst → 1 (single shared Redis instance).
+ *
+ * @param {string} runEnvKey - dev | tst
+ * @returns {number|null} Index or null if not applicable
+ */
+function redisDbIndexForScopedRunEnv(runEnvKey) {
+  if (!runEnvKey || typeof runEnvKey !== 'string') return null;
+  const k = runEnvKey.toLowerCase();
+  if (k === 'dev') return 0;
+  if (k === 'tst') return 1;
+  return null;
+}
+
+/**
+ * Docker container name for local `aifabrix run` when env-scoping applies.
+ *
+ * @param {string} appName - Application key
+ * @param {string|number} devId - Developer id
+ * @param {number} idNum - Parsed numeric developer id
+ * @param {string} envKey - dev | tst
+ * @returns {string}
+ */
+function buildScopedLocalContainerName(appName, devId, idNum, envKey) {
+  const e = String(envKey).toLowerCase();
+  if (idNum === 0) {
+    return `aifabrix-${e}-${appName}`;
+  }
+  return `aifabrix-dev${devId}-${e}-${appName}`;
+}
+
+/**
+ * Default local container name (no env scope).
+ *
+ * @param {string} appName - Application key
+ * @param {string|number} devId - Developer id
+ * @param {number} idNum - Parsed numeric developer id
+ * @returns {string}
+ */
+function buildDefaultLocalContainerName(appName, devId, idNum) {
+  if (idNum === 0) {
+    return `aifabrix-${appName}`;
+  }
+  return `aifabrix-dev${devId}-${appName}`;
+}
+
+/**
+ * Resolved container name for run/stop/status.
+ *
+ * @param {string} appName - Application key
+ * @param {string|number} developerId - Developer id
+ * @param {boolean} effectiveScoped - From {@link computeEffectiveEnvironmentScopedResources}
+ * @param {string} [runEnvKey] - dev | tst (required when effectiveScoped)
+ * @returns {string}
+ */
+function resolveRunContainerName(appName, developerId, effectiveScoped, runEnvKey) {
+  const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
+  if (effectiveScoped && runEnvKey) {
+    return buildScopedLocalContainerName(appName, developerId, idNum, runEnvKey);
+  }
+  return buildDefaultLocalContainerName(appName, developerId, idNum);
+}
+
+/**
+ * Traefik PathPrefix: prefix /{envKey} before pattern base (e.g. /api → /dev/api).
+ *
+ * @param {string} basePath - From derivePathFromPattern
+ * @param {string} envKey - dev | tst
+ * @returns {string}
+ */
+function buildEnvScopedTraefikPath(basePath, envKey) {
+  const e = String(envKey).toLowerCase();
+  const trimmed = (basePath || '/').trim() || '/';
+  if (trimmed === '/') {
+    return `/${e}`;
+  }
+  const withSlash = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+  return `/${e}${withSlash}`.replace(/\/{2,}/g, '/');
+}
+
+/**
+ * Compose service + Traefik router key when env-scoped (unique per env on shared host).
+ *
+ * @param {string} appName - Application key
+ * @param {string} envKey - dev | tst
+ * @returns {string}
+ */
+function composeTraefikServiceKey(appName, envKey) {
+  return `${String(envKey).toLowerCase()}-${appName}`;
+}
+
+module.exports = {
+  isScopedRunEnvironmentKey,
+  computeEffectiveEnvironmentScopedResources,
+  redisDbIndexForScopedRunEnv,
+  buildScopedLocalContainerName,
+  buildDefaultLocalContainerName,
+  resolveRunContainerName,
+  buildEnvScopedTraefikPath,
+  composeTraefikServiceKey
+};

package/lib/utils/error-formatter.js

@@ -19,6 +19,8 @@ const PATTERN_DESCRIPTIONS = {
   '^[a-z-]+$': 'lowercase letters and hyphens only',
   '^[A-Z_][A-Z0-9_]*$': 'uppercase letters, numbers, and underscores (must start with letter or underscore)',
   '^[a-zA-Z0-9_-]+$': 'letters, numbers, hyphens, and underscores only',
+  '^[a-zA-Z0-9_]+$': 'letters, numbers, and underscores only',
+  '^[a-zA-Z0-9_.]+$': 'letters, numbers, underscores, and dots only',
   '^(http|https)://.*$': 'valid HTTP or HTTPS URL',
   '^/[a-z0-9/-]*$': 'URL path starting with / (lowercase letters, numbers, hyphens, slashes)'
 };
@@ -45,15 +47,52 @@ function getFieldName(error) {
   return path ? `Field "${path}"` : 'Configuration';
 }
 
+/**
+ * Resolves a value from root using an AJV instancePath (JSON Pointer, e.g. /roles/0/value).
+ * @param {*} root - Object or array validated at root
+ * @param {string} instancePath - AJV instancePath (leading slash or empty)
+ * @returns {*|undefined}
+ */
+function getValueAtInstancePath(root, instancePath) {
+  if (root === undefined || root === null) return undefined;
+  if (!instancePath || instancePath === '' || instancePath === '/') return root;
+  const parts = instancePath.split('/').filter(Boolean);
+  let cur = root;
+  for (const p of parts) {
+    if (cur === undefined || cur === null) return undefined;
+    const key = /^\d+$/.test(p) ? parseInt(p, 10) : p;
+    cur = cur[key];
+  }
+  return cur;
+}
+
+/**
+ * Resolves the failing value for display (AJV may omit `data` depending on compile options).
+ * @param {Object} error - AJV error
+ * @param {Object} [options] - rootData or deploymentManifest (same shape as validated root)
+ * @returns {*|undefined}
+ */
+function resolveErrorDataValue(error, options = {}) {
+  if (error && error.data !== undefined) return error.data;
+  const root = options.rootData !== undefined ? options.rootData : options.deploymentManifest;
+  if (!root) return undefined;
+  return getValueAtInstancePath(root, error.instancePath || '');
+}
+
 /**
  * Formats a pattern validation error with the actual invalid value
  * @function formatPatternError
  * @param {string} field - Field name
  * @param {Object} error - Validation error object
+ * @param {Object} [options] - Pass rootData or deploymentManifest to show value when error.data is missing
  * @returns {string} Formatted error message
  */
-function formatPatternError(field, error) {
-  const invalidValue = error.data !== undefined ? `"${error.data}"` : 'value';
+function formatPatternError(field, error, options = {}) {
+  const actual = resolveErrorDataValue(error, options);
+  const invalidValue =
+    actual === undefined
+      ? '(unavailable — pass rootData/deploymentManifest to formatValidationErrors to show it)'
+      : JSON.stringify(actual);
   const patternDesc = getPatternDescription(error.params?.pattern);
   return `${field}: Invalid value ${invalidValue} - ${patternDesc}`;
 }
@@ -119,6 +158,10 @@ function createKeywordFormatters(field, error) {
       ? `${field}: Must be at most ${params.limit} characters`
       : `${field}: Too long`,
 
+    minItems: params.limit !== undefined
+      ? `${field}: must have at least ${params.limit} item(s)`
+      : `${field}: too few items`,
+
     enum: params.allowedValues && params.allowedValues.length > 0
       ? `${field}: Must be one of: ${params.allowedValues.join(', ')}`
       : `${field}: Must be one of: unknown`
@@ -126,22 +169,93 @@ function createKeywordFormatters(field, error) {
 }
 
 /**
- * Formats a single validation error into a developer-friendly message
- *
- * @function formatSingleError
+ * Formats oneOf/anyOf validation errors with actionable message
+ * @param {string} field - Field name
+ * @param {Object} error - AJV error (keyword oneOf or anyOf)
+ * @returns {string} Formatted error message
+ */
+function formatOneOfAnyOfError(field, error) {
+  const instancePath = (error.instancePath || '').replace(/^\//, '');
+  if (instancePath === 'capabilities') {
+    return `${field}: must be either an array of operation names (e.g. ["list","get"]) or an object with boolean flags (e.g. { "list": true }).`;
+  }
+  return `${field}: value does not match any allowed shape. Check type and required fields.`;
+}
+
+/**
+ * Formats const validation errors
+ * @param {string} field - Field name
+ * @param {Object} error - AJV error (keyword const)
+ * @returns {string} Formatted error message
+ */
+function formatConstError(field, error) {
+  const allowed = error.params?.allowedValue;
+  if (allowed !== undefined) {
+    const display = typeof allowed === 'string' ? `"${allowed}"` : String(allowed);
+    return `${field}: must be exactly ${display}`;
+  }
+  return `${field}: invalid value (constraint violation)`;
+}
+
+/** JSON Pointer: /permissions/<index>/roles */
+const PERMISSION_ROLES_INSTANCE_PATH = /^\/permissions\/(\d+)\/roles$/;
+
+/**
+ * Clear message when permissions[i].roles is [] (schema minItems: 1).
+ * @param {Object} error - AJV error
+ * @param {Object} [options] - Optional context
+ * @param {Object} [options.deploymentManifest] - Deploy JSON being validated (for permission name)
+ * @returns {string|null}
+ */
+function tryFormatPermissionRolesMinItemsError(error, options) {
+  if (error.keyword !== 'minItems') {
+    return null;
+  }
+  const m = (error.instancePath || '').match(PERMISSION_ROLES_INSTANCE_PATH);
+  if (!m) {
+    return null;
+  }
+  const idx = parseInt(m[1], 10);
+  const perms = options?.deploymentManifest?.permissions;
+  const perm = Array.isArray(perms) ? perms[idx] : null;
+  const named =
+    perm && typeof perm.name === 'string' && perm.name.trim()
+      ? ` "${perm.name.trim()}"`
+      : ` at permissions[${idx}]`;
+  return (
+    `RBAC: permission${named} has an empty "roles" array. ` +
+    'Each permission must list at least one role, and each string must match a role "value" from your "roles" list ' +
+    '(in application.yaml or rbac.yaml under the app folder). ' +
+    'Add roles, e.g. roles: ["admin"], or remove the permission if it is unused.'
+  );
+}
+
+/**
  * @param {Object} error - Raw validation error from Ajv
+ * @param {Object} [options] - Optional; use deploymentManifest for richer RBAC messages
  * @returns {string} Formatted error message
  */
-function formatSingleError(error) {
+function formatSingleError(error, options) {
   const field = getFieldName(error);
 
+  const rbacRolesMsg = tryFormatPermissionRolesMinItemsError(error, options);
+  if (rbacRolesMsg) {
+    return rbacRolesMsg;
+  }
+
   // Handle pattern errors with special formatting
   if (error.keyword === 'pattern') {
-    return formatPatternError(field, error);
+    return formatPatternError(field, error, options);
   }
   if (error.keyword === 'additionalProperties') {
     return formatAdditionalPropertiesError(field, error);
   }
+  if (error.keyword === 'oneOf' || error.keyword === 'anyOf') {
+    return formatOneOfAnyOfError(field, error);
+  }
+  if (error.keyword === 'const') {
+    return formatConstError(field, error);
+  }
 
   // Use object lookup for keyword-specific messages
   const formatters = createKeywordFormatters(field, error);
@@ -157,18 +271,19 @@ function formatSingleError(error) {
  *
  * @function formatValidationErrors
  * @param {Array} errors - Raw validation errors from Ajv
+ * @param {Object} [options] - Optional; pass `{ deploymentManifest }` or `{ rootData }` for RBAC/pattern detail
  * @returns {Array} Formatted error messages
  *
  * @example
  * const messages = formatValidationErrors(ajvErrors);
  * // Returns: ['Port must be between 1 and 65535', 'Missing required field: displayName']
  */
-function formatValidationErrors(errors) {
+function formatValidationErrors(errors, options) {
   if (!Array.isArray(errors)) {
     return ['Unknown validation error'];
   }
 
-  return errors.map(formatSingleError);
+  return errors.map((e) => formatSingleError(e, options));
 }
 
 /**
@@ -195,5 +310,6 @@ module.exports = {
   formatValidationErrors,
   formatMissingDbPasswordError,
   getPatternDescription,
+  getValueAtInstancePath,
   PATTERN_DESCRIPTIONS
 };

package/lib/utils/error-formatters/http-status-errors.js

@@ -1,3 +1,4 @@
+const { formatBlockingError } = require('../cli-test-layout-chalk');
 /**
  * HTTP Status Error Formatters
  *
@@ -123,7 +124,7 @@ function addAuthenticationGuidance(lines, errorData) {
 
 function formatAuthenticationError(errorData) {
   const lines = [];
-  lines.push(chalk.red('❌ Authentication Failed\n'));
+  lines.push(formatBlockingError('Authentication Failed\n'));
 
   addControllerUrlInfo(lines, errorData);
   addAttemptedUrlsInfo(lines, errorData);
@@ -148,7 +149,7 @@ function formatAuthenticationError(errorData) {
  */
 function formatServerError(errorData) {
   const lines = [];
-  lines.push(chalk.red('❌ Server Error\n'));
+  lines.push(formatBlockingError('Server Error\n'));
 
   // Show controller URL if available
   if (errorData.controllerUrl) {
@@ -183,7 +184,7 @@ function formatServerError(errorData) {
  */
 function formatConflictError(errorData) {
   const lines = [];
-  lines.push(chalk.red('❌ Conflict\n'));
+  lines.push(formatBlockingError('Conflict\n'));
 
   // Show controller URL if available
   if (errorData.controllerUrl) {
@@ -252,7 +253,7 @@ function getNotFoundGuidance(detail) {
  */
 function formatNotFoundError(errorData) {
   const lines = [];
-  lines.push(chalk.red('❌ Not Found\n'));
+  lines.push(formatBlockingError('Not Found\n'));
 
   // Show controller URL if available
   if (errorData.controllerUrl) {
@@ -289,7 +290,7 @@ function formatNotFoundError(errorData) {
  */
 function formatGenericError(errorData, statusCode) {
   const lines = [];
-  lines.push(chalk.red(`❌ Error (HTTP ${statusCode})\n`));
+  lines.push(chalk.red(`✖ Error (HTTP ${statusCode})\n`));
 
   // Show controller URL if available
   if (errorData.controllerUrl) {

package/lib/utils/error-formatters/network-errors.js

@@ -1,3 +1,4 @@
+const { formatBlockingError } = require('../cli-test-layout-chalk');
 /**
  * Network Error Formatters
  *
@@ -135,7 +136,7 @@ function addCorrelationId(lines, errorData) {
  */
 function formatNetworkError(errorMessage, errorData) {
   const lines = [];
-  lines.push(chalk.red('❌ Network Error\n'));
+  lines.push(formatBlockingError('Network Error\n'));
 
   addControllerUrlHeader(lines, errorData);
 

package/lib/utils/error-formatters/permission-errors.js

@@ -1,3 +1,4 @@
+const { formatBlockingError } = require('../cli-test-layout-chalk');
 /**
  * Permission Error Formatters
  *
@@ -103,7 +104,7 @@ function getPermissionDetailLines(errorData) {
  */
 function formatPermissionError(errorData) {
   const lines = [];
-  lines.push(chalk.red('❌ Permission Denied\n'));
+  lines.push(formatBlockingError('Permission Denied\n'));
 
   if (errorData.detail) {
     lines.push(chalk.yellow(errorData.detail));

package/lib/utils/error-formatters/validation-errors.js

@@ -1,3 +1,4 @@
+const { formatBlockingError } = require('../cli-test-layout-chalk');
 /**
  * Validation Error Formatters
  *
@@ -111,7 +112,7 @@ function addValidationGuidance(lines, hasErrors) {
  */
 function formatValidationError(errorData) {
   const lines = [];
-  lines.push(chalk.red('❌ Validation Error\n'));
+  lines.push(formatBlockingError('Validation Error\n'));
 
   addValidationErrorMessage(lines, errorData);
   addValidationErrorsList(lines, errorData.errors);

package/lib/utils/external-env-template.js

@@ -0,0 +1,180 @@
+/**
+ * Builds Handlebars context and generates env.template content for external systems.
+ * Single source for create, download, split, and repair so env.template structure is consistent.
+ *
+ * @fileoverview External system env.template generation
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const Handlebars = require('handlebars');
+const { systemKeyToKvPrefix, kvEnvKeyToPath, securityKeyToVar } = require('./credential-secrets-env');
+
+/**
+ * Builds hint string from portalInput (options → enum, validation → min-max or pattern).
+ * @param {Object} portalInput - Portal input config (label, options, validation)
+ * @returns {string} Hint suffix for comment
+ */
+function buildPortalInputHint(portalInput) {
+  if (!portalInput || typeof portalInput !== 'object') return '';
+  const parts = [];
+  if (Array.isArray(portalInput.options) && portalInput.options.length > 0) {
+    parts.push(`enum ${portalInput.options.join(',')}`);
+  }
+  const v = portalInput.validation;
+  if (v && typeof v === 'object') {
+    if (typeof v.minLength === 'number' || typeof v.maxLength === 'number') {
+      parts.push('min-max');
+    } else if (typeof v.pattern === 'string' && v.pattern) {
+      parts.push('pattern');
+    }
+  }
+  return parts.length ? ` - ${parts.join(', ')}` : '';
+}
+
+/** Fallback security keys by auth method when authentication.security is absent. */
+const FALLBACK_SECURITY_BY_AUTH = {
+  oauth2: ['clientId', 'clientSecret'],
+  oauth: ['clientId', 'clientSecret'],
+  aad: ['clientId', 'clientSecret'],
+  apikey: ['apiKey'],
+  apiKey: ['apiKey'],
+  basic: ['username', 'password'],
+  queryParam: ['paramValue'],
+  oidc: [],
+  hmac: ['signingSecret'],
+  bearer: ['bearerToken'],
+  token: ['bearerToken'],
+  none: []
+};
+
+/**
+ * Builds authSecureVars array from system authentication.security (or fallback by auth type).
+ * @param {Object} system - System object with key and authentication
+ * @returns {Array<{name: string, value: string}>}
+ */
+function buildAuthSecureVarsFromSystem(system) {
+  const authSecureVars = [];
+  const systemKey = system?.key || 'external-system';
+  const prefix = systemKeyToKvPrefix(systemKey);
+  if (!prefix) return authSecureVars;
+  const security = system?.authentication?.security || system?.auth?.security;
+  const authMethod = (system?.authentication?.method || system?.authentication?.type ||
+    system?.auth?.method || system?.auth?.type || 'apikey').toLowerCase();
+  if (security && typeof security === 'object' && Object.keys(security).length > 0) {
+    for (const key of Object.keys(security)) {
+      const envName = `KV_${prefix}_${securityKeyToVar(key)}`;
+      const pathVal = kvEnvKeyToPath(envName, systemKey);
+      authSecureVars.push({ name: envName, value: pathVal || `kv://${systemKey}/${key}` });
+    }
+  } else {
+    const keys = FALLBACK_SECURITY_BY_AUTH[authMethod] || FALLBACK_SECURITY_BY_AUTH.apikey;
+    for (const key of keys) {
+      authSecureVars.push({
+        name: `KV_${prefix}_${securityKeyToVar(key)}`,
+        value: `kv://${systemKey}/${key}`
+      });
+    }
+  }
+  return authSecureVars;
+}
+
+/**
+ * Builds configuration array with name, value, comment from system.configuration.
+ * @param {Object} system - System object with configuration array
+ * @returns {Array<{name: string, value: string, comment: string}>}
+ */
+function buildConfigurationEntries(system) {
+  const configuration = [];
+  const configList = Array.isArray(system?.configuration) ? system.configuration : [];
+  for (const entry of configList) {
+    if (!entry || !entry.name) continue;
+    const label = entry.portalInput?.label || entry.name;
+    const hint = buildPortalInputHint(entry.portalInput || {});
+    let value = entry.value !== undefined && entry.value !== null ? String(entry.value) : '';
+    if (entry.location === 'keyvault' && value && !value.startsWith('kv://')) value = `kv://${value}`;
+    configuration.push({ name: entry.name, value, comment: `${label}${hint}` });
+  }
+  return configuration;
+}
+
+/**
+ * Builds template context from system object for env.template.hbs.
+ * @param {Object} system - Full system object (e.g. deployment.system or parsed system file)
+ * @returns {{ authMethod: string, authSecureVars: Array<{name: string, value: string}>, authNonSecureVarNames: string[], configuration: Array<{name: string, value: string, comment: string}> }}
+ */
+function buildExternalEnvTemplateContext(system) {
+  const authMethod = (system?.authentication?.method ||
+    system?.authentication?.type ||
+    system?.auth?.method ||
+    system?.auth?.type ||
+    'apikey').toLowerCase();
+  const authSecureVars = buildAuthSecureVarsFromSystem(system);
+  const authVars = system?.authentication?.variables || system?.auth?.variables || {};
+  const authNonSecureVarNames = Object.keys(authVars);
+  const configuration = buildConfigurationEntries(system);
+  return {
+    authMethod,
+    authSecureVars,
+    authNonSecureVarNames,
+    configuration
+  };
+}
+
+/** Inline fallback when env.template.hbs is missing or unreadable (e.g. CI path or bundled). */
+const DEFAULT_ENV_TEMPLATE_HBS = `# Environment variables for external system integration
+# Use kv:// (or aifabrix secret set) for sensitive values; plain values for non-sensitive configuration.
+#
+
+{{#if authMethod}}
+# Authentication
+# Type: {{authMethod}}
+{{#each authSecureVars}}
+{{name}}={{value}}
+{{/each}}
+{{#if authNonSecureVarNames}}
+# Non-secure (e.g. URLs): {{#each authNonSecureVarNames}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}
+{{/if}}
+
+{{/if}}
+{{#if configuration.length}}
+# Configuration
+{{#each configuration}}
+# {{comment}}
+{{name}}={{value}}
+{{/each}}
+{{/if}}
+`;
+
+/**
+ * Generates env.template content from system using the Handlebars template.
+ * @param {Object} system - Full system object (e.g. deployment.system or parsed system file)
+ * @returns {string} Rendered env.template content
+ */
+function generateExternalEnvTemplateContent(system) {
+  if (!system || typeof system !== 'object') {
+    return '# Environment variables for external system integration\n# Use kv:// (or aifabrix secret set) for sensitive values.\n\n';
+  }
+  let templateContent;
+  try {
+    const templatePath = path.join(__dirname, '..', '..', 'templates', 'external-system', 'env.template.hbs');
+    templateContent = fs.readFileSync(templatePath, 'utf8');
+  } catch (_) {
+    templateContent = undefined;
+  }
+  if (typeof templateContent !== 'string' || !templateContent.trim()) {
+    templateContent = DEFAULT_ENV_TEMPLATE_HBS;
+  }
+  const template = Handlebars.compile(templateContent);
+  const context = buildExternalEnvTemplateContext(system);
+  return template(context);
+}
+
+module.exports = {
+  buildExternalEnvTemplateContext,
+  generateExternalEnvTemplateContent
+};

package/lib/utils/external-readme.js

@@ -133,6 +133,10 @@ function buildSecretPaths(systemKey, authType) {
  * @param {Object} [params.authentication] - Full authentication object (authType used if authType not set)
  * @returns {Object} Template context
  */
+function rbacOptionalFilename(normalizedExt) {
+  return normalizedExt === '.yaml' || normalizedExt === '.yml' ? 'rbac.yaml' : 'rbac.json';
+}
+
 function buildExternalReadmeContext(params = {}) {
   const appName = params.appName || params.systemKey || 'external-system';
   const systemKey = params.systemKey || appName;
@@ -140,9 +144,11 @@ function buildExternalReadmeContext(params = {}) {
   const description = params.description || `External system integration for ${systemKey}`;
   const systemType = params.systemType || 'openapi';
   const fileExt = params.fileExt !== undefined ? params.fileExt : '.json';
+  const normalizedExt = fileExt && fileExt.startsWith('.') ? fileExt : `.${fileExt || 'json'}`;
   const datasources = normalizeDatasources(params.datasources, systemKey, fileExt);
   const authType = params.authType || params.authentication?.type || params.authentication?.method || params.authentication?.authType;
   const secretPaths = buildSecretPaths(systemKey, authType);
+  const rbacOptionalFile = rbacOptionalFilename(normalizedExt);
 
   return {
     appName,
@@ -150,7 +156,8 @@ function buildExternalReadmeContext(params = {}) {
     displayName,
     description,
     systemType,
-    fileExt: fileExt && fileExt.startsWith('.') ? fileExt : `.${fileExt || 'json'}`,
+    fileExt: normalizedExt,
+    rbacOptionalFile,
     datasourceCount: datasources.length,
     hasDatasources: datasources.length > 0,
     datasources,