@aifabrix/builder 2.43.0 → 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

@@ -47,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}`;
 }
@@ -121,19 +158,16 @@ 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`
   };
 }
 
-/**
- * Formats a single validation error into a developer-friendly message
- *
- * @function formatSingleError
- * @param {Object} error - Raw validation error from Ajv
- * @returns {string} Formatted error message
- */
 /**
  * Formats oneOf/anyOf validation errors with actionable message
  * @param {string} field - Field name
@@ -163,12 +197,55 @@ function formatConstError(field, error) {
   return `${field}: invalid value (constraint violation)`;
 }
 
-function formatSingleError(error) {
+/** 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, 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);
@@ -194,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));
 }
 
 /**
@@ -232,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-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,