@aifabrix/builder 2.42.1 → 2.44.0

package/lib/commands/repair-datasource.js

@@ -1,18 +1,17 @@
 /**
  * Datasource repair helpers: align dimensions, metadataSchema, exposed, sync, testPayload
- * with fieldMappings.attributes as source of truth.
+ * with fieldMappings.attributes as source of truth (external-datasource schema v2.4+).
  *
  * @fileoverview Repair datasource files for external integration
  * @author AI Fabrix Team
- * @version 2.0.0
+ * @version 2.2.0
  */
 
 'use strict';
 
 const DEFAULT_SYNC = {
   mode: 'pull',
-  batchSize: 500,
-  maxParallelRequests: 5
+  batchSize: 500
 };
 
 const MINIMAL_METADATA_SCHEMA = {
@@ -20,6 +19,61 @@ const MINIMAL_METADATA_SCHEMA = {
   additionalProperties: true
 };
 
+/** Plan 346 / v2.4.1 closed root for testPayload */
+const TEST_PAYLOAD_TOP_LEVEL_ALLOW = new Set([
+  'mode',
+  'primaryKey',
+  'scenarios',
+  'fk',
+  'actors',
+  'payloadTemplate',
+  'expectedResult'
+]);
+
+/**
+ * @param {string|undefined} entityType - entityType from datasource
+ * @returns {boolean}
+ */
+function isNoneEntityType(entityType) {
+  return entityType === 'none';
+}
+
+/**
+ * @param {string|undefined} entityType - entityType from datasource
+ * @returns {boolean}
+ */
+function isStorageEntityType(entityType) {
+  return entityType === 'recordStorage' || entityType === 'documentStorage';
+}
+
+/**
+ * Ensures metadataSchema.properties.externalId for recordStorage/documentStorage (schema v2.4).
+ * @param {Object} parsed - Parsed datasource (mutated)
+ * @param {string[]} changes - Change log
+ * @returns {boolean} True if externalId was added or corrected
+ */
+function ensureStorageExternalIdMetadataProperty(parsed, changes) {
+  if (!isStorageEntityType(parsed?.entityType)) return false;
+  if (!parsed.metadataSchema || typeof parsed.metadataSchema !== 'object') return false;
+  if (!parsed.metadataSchema.properties || typeof parsed.metadataSchema.properties !== 'object') {
+    parsed.metadataSchema.properties = {};
+  }
+  const props = parsed.metadataSchema.properties;
+  const ext = props.externalId;
+  const ok = ext
+    && typeof ext === 'object'
+    && ext.type === 'string'
+    && ext.index === true;
+  if (ok) return false;
+  props.externalId = {
+    ...(typeof ext === 'object' && ext !== null ? ext : {}),
+    type: 'string',
+    index: true
+  };
+  changes.push('Ensured metadataSchema.properties.externalId (type string, index true) for storage entityType');
+  return true;
+}
+
 /**
  * Returns the set of attribute keys from fieldMappings.attributes.
  * @param {Object} parsed - Parsed datasource object
@@ -32,12 +86,24 @@ function getAttributeKeys(parsed) {
 }
 
 /**
- * Extracts paths from attribute expressions (e.g. {{ metadata.email }}).
+ * @param {string} path - Normalized path (raw. prefix already stripped)
+ * @param {string[]} paths
+ * @param {Set<string>} topLevelKeys
+ * @param {Set<string>} referencedSchemaPropertyNames
+ */
+function accumulatePathSegments(path, paths, topLevelKeys, referencedSchemaPropertyNames) {
+  paths.push(path);
+  const segments = path.split('.');
+  const first = segments[0];
+  if (first) topLevelKeys.add(first);
+  if (first === 'metadata' && segments.length >= 2 && segments[1]) {
+    referencedSchemaPropertyNames.add(segments[1]);
+  }
+}
+
+/**
+ * Extracts paths from attribute expressions (e.g. {{ metadata.email }}, {{ raw.id }}).
  * Skips record_ref: expressions.
- * - topLevelKeys: first segment of each path (e.g. "metadata" from "metadata.id").
- * - referencedSchemaPropertyNames: for paths like "metadata.xxx" or "metadata.xxx.yyy", the name "xxx"
- *   (the first property under metadata). Used to prune metadataSchema.properties so we only keep
- *   properties that are referenced; we do not compare against "metadata" or the schema would be wiped.
  *
  * @param {Object} attributes - fieldMappings.attributes object
  * @returns {{ paths: string[], topLevelKeys: Set<string>, referencedSchemaPropertyNames: Set<string> }}
@@ -46,111 +112,246 @@ function parsePathsFromExpressions(attributes) {
   const paths = [];
   const topLevelKeys = new Set();
   const referencedSchemaPropertyNames = new Set();
-  if (!attributes || typeof attributes !== 'object') return { paths, topLevelKeys, referencedSchemaPropertyNames };
+  if (!attributes || typeof attributes !== 'object') {
+    return { paths, topLevelKeys, referencedSchemaPropertyNames };
+  }
   for (const attr of Object.values(attributes)) {
     const expr = attr?.expression;
     if (typeof expr !== 'string') continue;
     if (/^\s*record_ref:/i.test(expr.trim())) continue;
     const match = expr.match(/\{\{\s*([^}]+)\s*\}\}/);
     if (!match) continue;
-    const path = match[1].trim().split('|')[0].trim();
-    if (path) {
-      paths.push(path);
-      const segments = path.split('.');
-      const first = segments[0];
-      if (first) topLevelKeys.add(first);
-      if (first === 'metadata' && segments.length >= 2 && segments[1]) {
-        referencedSchemaPropertyNames.add(segments[1]);
-      }
-    }
+    let path = match[1].trim().split('|')[0].trim();
+    if (path.startsWith('raw.')) path = path.slice(4);
+    if (path) accumulatePathSegments(path, paths, topLevelKeys, referencedSchemaPropertyNames);
   }
   return { paths, topLevelKeys, referencedSchemaPropertyNames };
 }
 
 /**
- * Removes dimension entries whose value is metadata.<attr> and attr is not in fieldMappings.attributes.
- * Mutates parsed.fieldMappings.dimensions.
- *
+ * @param {Object} binding - dimension binding
+ * @param {string} dimKey - dimension key
+ * @param {string[]} changes - Change log
+ * @returns {boolean}
+ */
+function removeOperatorWithoutActor(binding, dimKey, changes) {
+  if (binding.operator && !binding.actor) {
+    delete binding.operator;
+    changes.push(`Removed 'operator' from dimension '${dimKey}' (no actor)`);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * @param {string} dimKey - dimension key
+ * @param {Object} binding - dimension binding
+ * @param {string[]} changes - Change log
+ * @returns {boolean}
+ */
+function repairFkDimensionBinding(dimKey, binding, changes) {
+  let updated = false;
+  if (binding.field !== undefined) {
+    delete binding.field;
+    changes.push(`Removed invalid 'field' from FK dimension '${dimKey}'`);
+    updated = true;
+  }
+  return removeOperatorWithoutActor(binding, dimKey, changes) || updated;
+}
+
+/**
+ * @param {string} dimKey - dimension key
+ * @param {Object} binding - dimension binding
+ * @param {string[]} changes - Change log
+ * @returns {boolean}
+ */
+function repairLocalDimensionBinding(dimKey, binding, changes) {
+  let updated = false;
+  if (binding.via !== undefined) {
+    delete binding.via;
+    changes.push(`Removed invalid 'via' from local dimension '${dimKey}'`);
+    updated = true;
+  }
+  return removeOperatorWithoutActor(binding, dimKey, changes) || updated;
+}
+
+/**
+ * Normalizes dimension bindings: FK vs local invariants; strip operator without actor.
+ * @param {Object} parsed - Parsed datasource (mutated)
+ * @param {string[]} changes - Change log
+ * @returns {boolean}
+ */
+function repairDimensionBindingShape(parsed, changes) {
+  const dims = parsed?.dimensions;
+  if (!dims || typeof dims !== 'object') return false;
+  let updated = false;
+  for (const [dimKey, binding] of Object.entries(dims)) {
+    if (!binding || typeof binding !== 'object') continue;
+    const t = binding.type;
+    if (t === 'fk') {
+      updated = repairFkDimensionBinding(dimKey, binding, changes) || updated;
+    } else if (t === 'local' || t === undefined) {
+      updated = repairLocalDimensionBinding(dimKey, binding, changes) || updated;
+    } else {
+      updated = removeOperatorWithoutActor(binding, dimKey, changes) || updated;
+    }
+  }
+  return updated;
+}
+
+/**
+ * Removes root local dimension bindings whose field is not in fieldMappings.attributes.
+ * Skips FK bindings.
  * @param {Object} parsed - Parsed datasource (mutated)
- * @param {string[]} changes - Array to append change descriptions to
+ * @param {string[]} changes - Change log
  * @returns {boolean} True if any dimension was removed
  */
-function repairDimensionsFromAttributes(parsed, changes) {
-  const dims = parsed?.fieldMappings?.dimensions;
+function repairRootDimensionsFromAttributes(parsed, changes) {
+  const dims = parsed?.dimensions;
   if (!dims || typeof dims !== 'object') return false;
   const attributeKeys = getAttributeKeys(parsed);
   let updated = false;
-  for (const [dimKey, value] of Object.entries(dims)) {
-    if (typeof value !== 'string') continue;
-    if (!value.startsWith('metadata.')) continue;
-    const attr = value.slice('metadata.'.length).trim();
-    if (!attr || attributeKeys.has(attr)) continue;
+  for (const [dimKey, binding] of Object.entries(dims)) {
+    if (!binding || typeof binding !== 'object') continue;
+    if (binding.type === 'fk') continue;
+    if (binding.type !== undefined && binding.type !== 'local') continue;
+    const field = binding.field;
+    if (typeof field !== 'string') continue;
+    if (attributeKeys.has(field)) continue;
     delete dims[dimKey];
-    changes.push(`Removed dimension '${dimKey}': ${value} not in fieldMappings.attributes`);
+    changes.push(`Removed root dimension '${dimKey}': field '${field}' not in fieldMappings.attributes`);
     updated = true;
   }
   return updated;
 }
 
 /**
- * Ensures metadataSchema exists (minimal stub if missing). If present, prunes top-level
- * properties not referenced by any attribute expression. Uses the first property name under
- * "metadata" in paths (e.g. metadata.id → "id") so we do not remove schema properties that
- * are referenced. If no metadata.xxx paths exist, we do not prune (keep all properties).
+ * Adds metadataSchema property stubs for metadata.* paths referenced in attributes.
+ * @param {Object} parsed - Parsed datasource (mutated)
+ * @param {Set<string>} referencedSchemaPropertyNames - Property names under metadata
+ * @param {string[]} changes - Change log
+ * @returns {boolean}
+ */
+function ensureMetadataSchemaPropertyStubs(parsed, referencedSchemaPropertyNames, changes) {
+  if (!referencedSchemaPropertyNames || referencedSchemaPropertyNames.size === 0) return false;
+  if (!parsed.metadataSchema || typeof parsed.metadataSchema !== 'object') return false;
+  if (!parsed.metadataSchema.properties || typeof parsed.metadataSchema.properties !== 'object') {
+    parsed.metadataSchema.properties = {};
+  }
+  const props = parsed.metadataSchema.properties;
+  const added = [];
+  for (const name of referencedSchemaPropertyNames) {
+    if (!name || props[name] !== undefined) continue;
+    props[name] = { type: 'string' };
+    added.push(name);
+  }
+  if (added.length === 0) return false;
+  changes.push(`Added metadataSchema.properties stubs for [${added.join(', ')}]`);
+  return true;
+}
+
+/**
+ * @param {Object} parsed - Parsed datasource (mutated)
+ * @param {Set<string>} referencedSchemaPropertyNames - metadata.* names from expressions
+ * @param {string[]} changes - Change log
+ * @returns {boolean}
+ */
+function pruneMetadataSchemaPropertiesByAttributeRefs(parsed, referencedSchemaPropertyNames, changes) {
+  const props = parsed.metadataSchema?.properties;
+  if (
+    !props || typeof props !== 'object'
+    || referencedSchemaPropertyNames.size === 0
+  ) {
+    return false;
+  }
+  const toRemove = Object.keys(props).filter(k => {
+    if (referencedSchemaPropertyNames.has(k)) return false;
+    if (isStorageEntityType(parsed.entityType) && k === 'externalId') return false;
+    return true;
+  });
+  if (toRemove.length === 0) return false;
+  toRemove.forEach(k => delete props[k]);
+  changes.push(`Pruned metadataSchema.properties: removed [${toRemove.join(', ')}] (not referenced by attributes)`);
+  return true;
+}
+
+/**
+ * Ensures metadataSchema exists (minimal stub if missing). Prunes top-level properties not
+ * referenced by metadata.* paths in expressions (after stripping raw. prefix).
+ * Skipped entirely for entityType 'none'.
  *
  * @param {Object} parsed - Parsed datasource (mutated)
- * @param {string[]} changes - Array to append change descriptions to
+ * @param {string[]} changes - Change log
  * @returns {boolean} True if schema was added or pruned
  */
 function repairMetadataSchemaFromAttributes(parsed, changes) {
+  if (isNoneEntityType(parsed?.entityType)) {
+    return false;
+  }
   const { referencedSchemaPropertyNames } = parsePathsFromExpressions(parsed?.fieldMappings?.attributes ?? {});
+  let updated = false;
+
   if (!parsed.metadataSchema || typeof parsed.metadataSchema !== 'object') {
-    parsed.metadataSchema = { ...MINIMAL_METADATA_SCHEMA };
+    parsed.metadataSchema = { ...MINIMAL_METADATA_SCHEMA, properties: {} };
     changes.push('Added minimal metadataSchema (was missing)');
-    return true;
+    ensureMetadataSchemaPropertyStubs(parsed, referencedSchemaPropertyNames, changes);
+    updated = true;
+  } else {
+    if (pruneMetadataSchemaPropertiesByAttributeRefs(parsed, referencedSchemaPropertyNames, changes)) {
+      updated = true;
+    }
+    if (ensureMetadataSchemaPropertyStubs(parsed, referencedSchemaPropertyNames, changes)) {
+      updated = true;
+    }
   }
-  const props = parsed.metadataSchema.properties;
-  if (!props || typeof props !== 'object') return false;
-  if (referencedSchemaPropertyNames.size === 0) return false;
-  const toRemove = Object.keys(props).filter(k => !referencedSchemaPropertyNames.has(k));
-  if (toRemove.length === 0) return false;
-  toRemove.forEach(k => delete props[k]);
-  changes.push(`Pruned metadataSchema.properties: removed [${toRemove.join(', ')}] (not referenced by attributes)`);
-  return true;
+  if (ensureStorageExternalIdMetadataProperty(parsed, changes)) {
+    updated = true;
+  }
+  return updated;
 }
 
 /**
- * Sets exposed.attributes to the list of fieldMappings.attributes keys (sorted).
- * Only when options.expose is true; caller should gate.
+ * Sets exposed.schema from fieldMappings.attributes keys (metadata.<key> leaves). v2.4 canonical.
+ * Removes deprecated exposed.attributes when present so output matches schema.
  *
  * @param {Object} parsed - Parsed datasource (mutated)
- * @param {string[]} changes - Array to append change descriptions to
+ * @param {string[]} changes - Change log
  * @returns {boolean} True if exposed was updated
  */
 function repairExposeFromAttributes(parsed, changes) {
   const keys = Array.from(getAttributeKeys(parsed)).filter(Boolean).sort();
   if (keys.length === 0) return false;
   if (!parsed.exposed) parsed.exposed = {};
-  const prev = parsed.exposed.attributes;
-  const same = Array.isArray(prev) && prev.length === keys.length && prev.every((v, i) => v === keys[i]);
-  if (same) return false;
-  parsed.exposed.attributes = keys;
-  changes.push(`Set exposed.attributes to [${keys.join(', ')}]`);
+  const schema = {};
+  keys.forEach(k => {
+    schema[k] = `metadata.${k}`;
+  });
+  const prev = parsed.exposed.schema;
+  const same = prev && typeof prev === 'object'
+    && keys.length === Object.keys(prev).length
+    && keys.every(k => prev[k] === schema[k]);
+  if (same && parsed.exposed.attributes === undefined) return false;
+  parsed.exposed.schema = schema;
+  if (parsed.exposed.attributes !== undefined) {
+    delete parsed.exposed.attributes;
+  }
+  changes.push(`Set exposed.schema for [${keys.join(', ')}]`);
   return true;
 }
 
 /**
- * Adds default sync section if missing or empty.
+ * Adds default sync section if missing or empty. Not applied for entityType 'none'.
  *
  * @param {Object} parsed - Parsed datasource (mutated)
- * @param {string[]} changes - Array to append change descriptions to
+ * @param {string[]} changes - Change log
  * @returns {boolean} True if sync was added
  */
 function repairSyncSection(parsed, changes) {
+  if (isNoneEntityType(parsed?.entityType)) return false;
   const sync = parsed.sync;
   if (sync && typeof sync === 'object' && Object.keys(sync).length > 0) return false;
   parsed.sync = { ...DEFAULT_SYNC };
-  changes.push('Added default sync section (mode: pull, batchSize: 500, maxParallelRequests: 5)');
+  changes.push('Added default sync section (mode: pull, batchSize: 500)');
   return true;
 }
 
@@ -173,11 +374,32 @@ function setNested(obj, pathParts, value) {
   if (last) cur[last] = value;
 }
 
+/**
+ * Removes unknown top-level keys from testPayload (v2.4.1 closed root).
+ * @param {Object} parsed - Parsed datasource (mutated)
+ * @param {string[]} changes - Change log
+ * @returns {boolean}
+ */
+function sanitizeTestPayloadTopLevel(parsed, changes) {
+  const tp = parsed?.testPayload;
+  if (!tp || typeof tp !== 'object' || Array.isArray(tp)) return false;
+  const removed = [];
+  for (const key of Object.keys(tp)) {
+    if (!TEST_PAYLOAD_TOP_LEVEL_ALLOW.has(key)) {
+      delete tp[key];
+      removed.push(key);
+    }
+  }
+  if (removed.length === 0) return false;
+  changes.push(`Removed unknown testPayload keys: [${removed.join(', ')}]`);
+  return true;
+}
+
 /**
  * Builds minimal payloadTemplate and expectedResult from attribute expression paths.
  *
  * @param {Object} parsed - Parsed datasource (mutated)
- * @param {string[]} changes - Array to append change descriptions to
+ * @param {string[]} changes - Change log
  * @returns {boolean} True if testPayload was added or updated
  */
 function repairTestPayload(parsed, changes) {
@@ -191,7 +413,10 @@ function repairTestPayload(parsed, changes) {
     expectedResult[key] = placeholder;
     const match = config?.expression?.match(/\{\{\s*([^}|]+)/);
     if (match) {
-      const path = match[1].trim();
+      let path = match[1].trim();
+      if (path.startsWith('raw.')) {
+        path = path.slice(4);
+      }
       setNested(payloadTemplate, path.split('.'), placeholder);
     }
   }
@@ -203,7 +428,7 @@ function repairTestPayload(parsed, changes) {
 }
 
 /**
- * Runs all requested datasource repairs. Core: dimensions + metadataSchema. Optional: expose, sync, testPayload.
+ * Runs all requested datasource repairs.
  *
  * @param {Object} parsed - Parsed datasource object (mutated)
  * @param {Object} options - { expose?: boolean, sync?: boolean, test?: boolean }
@@ -213,23 +438,44 @@ function repairTestPayload(parsed, changes) {
 function repairDatasourceFile(parsed, options = {}, changes = []) {
   const out = Array.isArray(changes) ? changes : [];
   let updated = false;
-  updated = repairDimensionsFromAttributes(parsed, out) || updated;
-  updated = repairMetadataSchemaFromAttributes(parsed, out) || updated;
-  if (options.expose) updated = repairExposeFromAttributes(parsed, out) || updated;
-  if (options.sync) updated = repairSyncSection(parsed, out) || updated;
-  if (options.test) updated = repairTestPayload(parsed, out) || updated;
+  const none = isNoneEntityType(parsed?.entityType);
+
+  if (!none) {
+    updated = repairDimensionBindingShape(parsed, out) || updated;
+    updated = repairRootDimensionsFromAttributes(parsed, out) || updated;
+    updated = repairMetadataSchemaFromAttributes(parsed, out) || updated;
+  }
+
+  if (options.expose) {
+    updated = repairExposeFromAttributes(parsed, out) || updated;
+  }
+
+  if (!none && options.sync) {
+    updated = repairSyncSection(parsed, out) || updated;
+  }
+
+  if (options.test) {
+    sanitizeTestPayloadTopLevel(parsed, out);
+    updated = repairTestPayload(parsed, out) || updated;
+    updated = sanitizeTestPayloadTopLevel(parsed, out) || updated;
+  }
+
   return { updated, changes: out };
 }
 
 module.exports = {
   getAttributeKeys,
   parsePathsFromExpressions,
-  repairDimensionsFromAttributes,
+  repairDimensionBindingShape,
+  repairRootDimensionsFromAttributes,
   repairMetadataSchemaFromAttributes,
   repairExposeFromAttributes,
   repairSyncSection,
   repairTestPayload,
+  sanitizeTestPayloadTopLevel,
   repairDatasourceFile,
   DEFAULT_SYNC,
-  MINIMAL_METADATA_SCHEMA
+  MINIMAL_METADATA_SCHEMA,
+  TEST_PAYLOAD_TOP_LEVEL_ALLOW,
+  isNoneEntityType
 };

package/lib/commands/repair-env-template.js

@@ -11,10 +11,11 @@ const path = require('path');
 const fs = require('fs');
 const { systemKeyToKvPrefix, kvEnvKeyToPath, securityKeyToVar } = require('../utils/credential-secrets-env');
 const { extractEnvTemplate } = require('../generator/split');
+const { generateExternalEnvTemplateContent } = require('../utils/external-env-template');
 
 /**
  * Normalizes a keyvault config entry to canonical KV_* name and path-style value.
- * Path format: kv://<system-key>/<variable> (e.g. kv://microsoft-teams/clientId).
+ * Path format: kv://<systemKey>/<variable> (e.g. kv://microsoft-teams/clientId).
  * @param {Object} entry - Config entry with name, value, location
  * @param {string} prefix - KV prefix (e.g. MICROSOFT_TEAMS)
  * @param {string} systemKey - System key (e.g. microsoft-teams) for path namespace
@@ -65,7 +66,7 @@ function addFromConfiguration(effective, config, prefix, seenNames, systemKey) {
 
 /**
  * Adds effective config entries from authentication.security.
- * Path format: kv://<system-key>/<variable> (e.g. kv://microsoft-teams/clientId).
+ * Path format: kv://<systemKey>/<variable> (e.g. kv://microsoft-teams/clientId).
  * @param {Array} effective - Mutable result array
  * @param {Object} systemParsed - Parsed system config
  * @param {string} prefix - KV prefix
@@ -126,20 +127,25 @@ function buildExpectedByKey(effective) {
 }
 
 /**
- * Creates env.template when missing. Returns true if created (and change pushed).
+ * Creates env.template when missing using the Handlebars template (Authentication + Configuration sections).
  * @param {string} envPath - Path to env.template
- * @param {Map<string, string>} expectedByKey - Expected key->line map
+ * @param {Map<string, string>} expectedByKey - Expected key->line map (fallback when no systemParsed)
  * @param {boolean} dryRun - If true, do not write
  * @param {string[]} changes - Array to append to
+ * @param {Object} [systemParsed] - Parsed system config for template context (preferred)
  * @returns {boolean}
  */
-function createEnvTemplateIfMissing(envPath, expectedByKey, dryRun, changes) {
+function createEnvTemplateIfMissing(envPath, expectedByKey, dryRun, changes, systemParsed) {
   if (fs.existsSync(envPath)) return false;
-  const lines = Array.from(expectedByKey.values());
-  const content = lines.join('\n');
-  if (!content) return false;
+  if (expectedByKey.size === 0) return false;
+  const content = systemParsed
+    ? generateExternalEnvTemplateContent(systemParsed)
+    : Array.from(expectedByKey.values()).join('\n');
+  if (!content || !content.trim()) return false;
+  const hasKeyValueLine = /^[A-Z_][A-Z0-9_]*=/m.test(content);
+  if (!hasKeyValueLine) return false;
   if (!dryRun) {
-    fs.writeFileSync(envPath, content + '\n', { mode: 0o644, encoding: 'utf8' });
+    fs.writeFileSync(envPath, content + (content.endsWith('\n') ? '' : '\n'), { mode: 0o644, encoding: 'utf8' });
   }
   changes.push('Created env.template from system configuration');
   return true;
@@ -236,7 +242,7 @@ function repairEnvTemplate(appPath, systemParsed, systemKey, dryRun, changes) {
   const expectedByKey = buildExpectedByKey(effective);
   const envPath = path.join(appPath, 'env.template');
 
-  if (createEnvTemplateIfMissing(envPath, expectedByKey, dryRun, changes)) {
+  if (createEnvTemplateIfMissing(envPath, expectedByKey, dryRun, changes, systemParsed)) {
     return true;
   }
   if (!fs.existsSync(envPath)) {

package/lib/commands/repair-rbac.js

@@ -10,10 +10,10 @@
 
 const path = require('path');
 const fs = require('fs');
-const yaml = require('js-yaml');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
-const { loadConfigFile } = require('../utils/config-format');
+const { loadConfigFile, writeConfigFile } = require('../utils/config-format');
+const { resolveRbacPath } = require('../utils/app-config-resolver');
 
 const DEFAULT_CAPABILITIES = ['list', 'get', 'create', 'update', 'delete'];
 
@@ -55,26 +55,30 @@ function collectPermissionNames(appPath, datasourceFiles) {
 }
 
 /**
- * Loads existing rbac or creates empty structure. Uses extractRbacFromSystem when provided.
+ * Loads existing RBAC file (rbac.yaml, rbac.yml, or rbac.json) or creates empty structure.
+ * Uses extractRbacFromSystem when no file exists. New file path respects format (rbac.json when format is 'json').
+ *
  * @param {string} appPath - Application path
  * @param {Object} [systemParsed] - Parsed system for extractRbacFromSystem
  * @param {Function} extractRbacFromSystem - (system) => rbac or null
- * @returns {{ rbac: Object, rbacPath: string, rbacYmlPath: string }}
+ * @param {string} [format] - 'json' or 'yaml'; used only when creating a new file (default 'yaml')
+ * @returns {{ rbac: Object, rbacPath: string }} rbacPath is resolved path or path.join(appPath, 'rbac.{json|yaml}') for new file
  */
-function loadOrCreateRbac(appPath, systemParsed, extractRbacFromSystem) {
-  const rbacPath = path.join(appPath, 'rbac.yaml');
-  const rbacYmlPath = path.join(appPath, 'rbac.yml');
+function loadOrCreateRbac(appPath, systemParsed, extractRbacFromSystem, format) {
+  const resolvedPath = resolveRbacPath(appPath);
   let rbac;
-  if (fs.existsSync(rbacPath)) {
-    rbac = loadConfigFile(rbacPath);
-  } else if (fs.existsSync(rbacYmlPath)) {
-    rbac = loadConfigFile(rbacYmlPath);
+  let rbacPath;
+  if (resolvedPath) {
+    rbac = loadConfigFile(resolvedPath);
+    rbacPath = resolvedPath;
   } else {
     rbac = extractRbacFromSystem(systemParsed) || { roles: [], permissions: [] };
     if (!Array.isArray(rbac.roles)) rbac.roles = [];
     if (!Array.isArray(rbac.permissions)) rbac.permissions = [];
+    const ext = (format === 'json') ? 'rbac.json' : 'rbac.yaml';
+    rbacPath = path.join(appPath, ext);
   }
-  return { rbac, rbacPath, rbacYmlPath };
+  return { rbac, rbacPath };
 }
 
 /**
@@ -123,31 +127,33 @@ function ensureDefaultRoles(rbac, systemKey, displayName, changes) {
     if (p.name && listGetPerms.includes(p.name) && !p.roles.includes(readerValue)) p.roles.push(readerValue);
     if (!p.roles.includes(adminValue)) p.roles.push(adminValue);
   }
-  changes.push('Added default Admin and Reader roles to rbac.yaml');
+  changes.push('Added default Admin and Reader roles to rbac file');
   return true;
 }
 
 /**
  * Merges RBAC from datasources: ensures permission per resourceType:capability, adds Admin/Reader roles if none.
+ * When creating a new RBAC file, uses rbac.json if format is 'json', otherwise rbac.yaml.
+ *
  * @param {string} appPath - Application path
  * @param {Object} systemParsed - Parsed system (key, displayName)
  * @param {string[]} datasourceFiles - Datasource file names
  * @param {Function} extractRbacFromSystem - (system) => rbac or null
- * @param {boolean} dryRun - If true, do not write
- * @param {string[]} changes - Array to append change descriptions to
+ * @param {{ format?: string, dryRun: boolean, changes: string[] }} options - format ('json'|'yaml'), dryRun, changes array
  * @returns {boolean} True if rbac was updated (or would be in dry-run)
  */
-function mergeRbacFromDatasources(appPath, systemParsed, datasourceFiles, extractRbacFromSystem, dryRun, changes) {
+function mergeRbacFromDatasources(appPath, systemParsed, datasourceFiles, extractRbacFromSystem, options) {
+  const { format = 'yaml', dryRun, changes } = options;
+  const rbacFormat = format === 'json' ? 'json' : 'yaml';
   const permissionNames = collectPermissionNames(appPath, datasourceFiles);
   if (permissionNames.size === 0) return false;
   const systemKey = systemParsed?.key || 'system';
   const displayName = systemParsed?.displayName || systemKey;
-  const { rbac, rbacPath, rbacYmlPath } = loadOrCreateRbac(appPath, systemParsed, extractRbacFromSystem);
+  const { rbac, rbacPath } = loadOrCreateRbac(appPath, systemParsed, extractRbacFromSystem, rbacFormat);
   let updated = addMissingPermissions(rbac, permissionNames, changes);
   updated = ensureDefaultRoles(rbac, systemKey, displayName, changes) || updated;
   if (updated && !dryRun) {
-    const outPath = fs.existsSync(rbacPath) ? rbacPath : (fs.existsSync(rbacYmlPath) ? rbacYmlPath : rbacPath);
-    fs.writeFileSync(outPath, yaml.dump(rbac, { indent: 2, lineWidth: -1 }), { mode: 0o644, encoding: 'utf8' });
+    writeConfigFile(rbacPath, rbac);
   }
   return updated;
 }