@aifabrix/builder 2.46.0 → 2.47.1

package/lib/datasource/capability/capability-manifest.js

@@ -0,0 +1,254 @@
+/**
+ * COM v2 capability object helpers for datasource manifests.
+ *
+ * @fileoverview capability-manifest
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const FORBIDDEN_ROOT_KEYS = new Set([
+  'context',
+  'origin',
+  'generatedBy',
+  'composition',
+  'generation',
+  'enterpriseResolver'
+]);
+
+const DEFAULT_RISK_BY_KEY = {
+  list: 'low',
+  get: 'low',
+  search: 'low',
+  create: 'medium',
+  update: 'medium',
+  delete: 'high'
+};
+
+const RESOURCE_TYPE_MAP = {
+  conversation: 'message',
+  user: 'employee',
+  person: 'employee',
+  record: 'document',
+  folder: 'document',
+  country: 'organization',
+  report: 'document',
+  calendar: 'event',
+  subscription: 'event'
+};
+
+/**
+ * @param {unknown} entry
+ * @returns {string}
+ */
+function capabilityKeyFromEntry(entry) {
+  if (typeof entry === 'string' && entry.trim()) {
+    return entry.trim();
+  }
+  if (entry && typeof entry === 'object' && typeof entry.key === 'string' && entry.key.trim()) {
+    return entry.key.trim();
+  }
+  return '';
+}
+
+/**
+ * @param {unknown} capabilities
+ * @returns {string[]}
+ */
+function listCapabilityKeys(capabilities) {
+  if (!Array.isArray(capabilities)) {
+    return [];
+  }
+  return capabilities.map(capabilityKeyFromEntry).filter(Boolean);
+}
+
+/**
+ * @param {unknown} capabilities
+ * @param {string} key
+ * @returns {boolean}
+ */
+function capabilitiesIncludes(capabilities, key) {
+  const target = String(key).toLowerCase();
+  return listCapabilityKeys(capabilities).some((item) => item.toLowerCase() === target);
+}
+
+/**
+ * @param {string} key
+ * @param {string} [displayName]
+ * @returns {object}
+ */
+function buildCapabilityObject(key, displayName) {
+  const normalized = String(key || '').trim();
+  const label = displayName && String(displayName).trim() ? String(displayName).trim() : 'records';
+  return {
+    key: normalized,
+    description: `${normalized} operation on ${label}`,
+    riskLevel: DEFAULT_RISK_BY_KEY[normalized.toLowerCase()] || 'medium',
+    approvalRequired: false
+  };
+}
+
+/**
+ * @param {object} parsed
+ * @returns {object[]}
+ */
+function normalizeCapabilitiesToObjects(parsed) {
+  const caps = parsed?.capabilities;
+  const displayName = parsed?.displayName || parsed?.key || 'records';
+  if (!Array.isArray(caps) || caps.length === 0) {
+    return [];
+  }
+  const out = [];
+  const seen = new Set();
+  caps.forEach((item) => {
+    if (typeof item === 'string' && item.trim()) {
+      const key = item.trim();
+      if (seen.has(key)) return;
+      seen.add(key);
+      out.push(buildCapabilityObject(key, displayName));
+      return;
+    }
+    if (!item || typeof item !== 'object') return;
+    const key = capabilityKeyFromEntry(item);
+    if (!key || seen.has(key)) return;
+    seen.add(key);
+    const row = buildCapabilityObject(key, displayName);
+    if (typeof item.description === 'string' && item.description.trim()) {
+      row.description = item.description.trim();
+    }
+    if (typeof item.riskLevel === 'string' && item.riskLevel.trim()) {
+      row.riskLevel = item.riskLevel.trim();
+    }
+    if (item.approvalRequired === true) {
+      row.approvalRequired = true;
+    }
+    out.push(row);
+  });
+  return out;
+}
+
+/**
+ * @param {object} node
+ * @returns {void}
+ */
+function stripSemanticExtras(node) {
+  if (!node || typeof node !== 'object') return;
+  const semantic = node.semantic;
+  if (semantic && typeof semantic === 'object') {
+    delete semantic.categories;
+    delete semantic.synonyms;
+    if (Object.keys(semantic).length === 0) {
+      delete node.semantic;
+    }
+  }
+  Object.values(node).forEach((value) => {
+    if (value && typeof value === 'object') {
+      if (Array.isArray(value)) {
+        value.forEach((item) => stripSemanticExtras(item));
+      } else {
+        stripSemanticExtras(value);
+      }
+    }
+  });
+}
+
+/**
+ * @param {object} parsed
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function removeForbiddenComRootKeys(parsed, changes) {
+  let updated = false;
+  FORBIDDEN_ROOT_KEYS.forEach((key) => {
+    if (Object.prototype.hasOwnProperty.call(parsed, key)) {
+      delete parsed[key];
+      changes.push(`Removed forbidden COM v2 root key: ${key}`);
+      updated = true;
+    }
+  });
+  return updated;
+}
+
+/**
+ * @param {object} parsed
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function stripFieldMappingSemanticExtras(parsed, changes) {
+  if (!parsed.fieldMappings) {
+    return false;
+  }
+  const before = JSON.stringify(parsed.fieldMappings);
+  stripSemanticExtras(parsed.fieldMappings);
+  if (JSON.stringify(parsed.fieldMappings) === before) {
+    return false;
+  }
+  changes.push('Removed fieldMappings.*.semantic.categories/synonyms (COM v2)');
+  return true;
+}
+
+/**
+ * @param {object} parsed
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function applyResourceTypeCatalogMap(parsed, changes) {
+  const resourceType = parsed.resourceType;
+  if (typeof resourceType !== 'string') {
+    return false;
+  }
+  const mapped = RESOURCE_TYPE_MAP[resourceType.trim()];
+  if (!mapped) {
+    return false;
+  }
+  parsed.resourceType = mapped;
+  changes.push(`Mapped resourceType ${resourceType} → ${mapped}`);
+  return true;
+}
+
+/**
+ * @param {object} parsed
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function migrateCapabilitiesToComObjects(parsed, changes) {
+  const caps = parsed.capabilities;
+  const needsObjectMigration = Array.isArray(caps)
+    && caps.some((item) => typeof item === 'string' || (item && typeof item === 'object' && !item.key));
+  const hasStringCapabilities = Array.isArray(caps) && caps.length > 0 && typeof caps[0] === 'string';
+  if (!needsObjectMigration && !hasStringCapabilities) {
+    return false;
+  }
+  parsed.capabilities = normalizeCapabilitiesToObjects(parsed);
+  changes.push('Migrated capabilities[] to COM v2 capability objects');
+  return true;
+}
+
+/**
+ * @param {object} parsed
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function repairComV2Manifest(parsed, changes) {
+  if (!parsed || typeof parsed !== 'object') {
+    return false;
+  }
+  return [
+    removeForbiddenComRootKeys(parsed, changes),
+    stripFieldMappingSemanticExtras(parsed, changes),
+    applyResourceTypeCatalogMap(parsed, changes),
+    migrateCapabilitiesToComObjects(parsed, changes)
+  ].some(Boolean);
+}
+
+module.exports = {
+  FORBIDDEN_ROOT_KEYS,
+  capabilityKeyFromEntry,
+  listCapabilityKeys,
+  capabilitiesIncludes,
+  buildCapabilityObject,
+  normalizeCapabilitiesToObjects,
+  stripSemanticExtras,
+  repairComV2Manifest
+};

package/lib/datasource/capability/capability-resolve.js

@@ -6,6 +6,8 @@
  * @version 2.0.0
  */
 
+const { capabilitiesIncludes } = require('./capability-manifest');
+
 /**
  * @param {object|undefined} operations
  * @param {string} logicalKey
@@ -146,10 +148,7 @@ function resolveProfileKeyForLogical(doc, logicalKey) {
  * @returns {boolean}
  */
 function capabilityLogicalExists(doc, name) {
-  if (
-    Array.isArray(doc.capabilities) &&
-    doc.capabilities.some((c) => String(c).toLowerCase() === String(name).toLowerCase())
-  ) {
+  if (capabilitiesIncludes(doc.capabilities, name)) {
     return true;
   }
   if (findMatchingOpsKeys(doc.openapi?.operations, name).length > 0) {

package/lib/datasource/capability/copy-operations.js

@@ -7,6 +7,7 @@
  */
 
 const { rewriteCapabilityReferences } = require('./reference-rewrite');
+const { capabilityKeyFromEntry } = require('./capability-manifest');
 const { jsonPointerPath } = require('./json-pointer');
 const { buildBasicExposureProfileArray } = require('./basic-exposure');
 const {
@@ -53,9 +54,10 @@ function removeCapability(doc, logicalKey) {
   const profileKey = resolveProfileKeyForLogical(doc, logicalKey);
 
   if (Array.isArray(doc.capabilities)) {
-    doc.capabilities = doc.capabilities.filter(
-      (c) => String(c).toLowerCase() !== String(logicalKey).toLowerCase()
-    );
+    doc.capabilities = doc.capabilities.filter((c) => {
+      const key = capabilityKeyFromEntry(c);
+      return key.toLowerCase() !== String(logicalKey).toLowerCase();
+    });
   }
   if (openapiKey && oo) {
     delete oo[openapiKey];

package/lib/datasource/capability/remove-operations.js

@@ -17,6 +17,7 @@ const {
   findMatchingOpsKeys,
   resolveProfileKeyForLogical
 } = require('./capability-resolve');
+const { capabilityKeyFromEntry } = require('./capability-manifest');
 
 /**
  * @param {unknown} capabilities
@@ -28,7 +29,7 @@ function findCapabilityIndex(capabilities, logicalName) {
     return -1;
   }
   return capabilities.findIndex(
-    (c) => String(c).toLowerCase() === String(logicalName).toLowerCase()
+    (c) => capabilityKeyFromEntry(c).toLowerCase() === String(logicalName).toLowerCase()
   );
 }
 

package/lib/datasource/capability/run-capability-copy.js

@@ -8,6 +8,7 @@
 
 const fs = require('node:fs');
 const path = require('path');
+const { loadConfigFile, writeConfigFile } = require('../../utils/config-format');
 const { writeBackup } = require('../../utils/integration-file-backup');
 const {
   resolveValidateInputPath,
@@ -46,6 +47,33 @@ function resolveCapabilityCopyInputPath(identifier) {
   return resolveValidateInputPath(trimmed);
 }
 
+/**
+ * Read a datasource config file (.json, .yaml, or .yml).
+ *
+ * @param {string} filePath
+ * @returns {object}
+ */
+function readDatasourceConfigFile(filePath) {
+  return loadConfigFile(filePath);
+}
+
+/**
+ * @param {string} filePath
+ * @returns {'json'|'yaml'}
+ */
+function inferDatasourceConfigFormat(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === '.json') {
+    return 'json';
+  }
+  if (ext === '.yaml' || ext === '.yml') {
+    return 'yaml';
+  }
+  throw new Error(
+    `Unsupported datasource config extension: ${ext || '(none)'}. Use .json, .yaml, or .yml`
+  );
+}
+
 /**
  * @param {string} filePath
  * @param {object} obj
@@ -53,9 +81,9 @@ function resolveCapabilityCopyInputPath(identifier) {
  */
 function atomicWriteJson(filePath, obj) {
   const dir = path.dirname(filePath);
+  const format = inferDatasourceConfigFormat(filePath);
   const tmp = path.join(dir, `.${path.basename(filePath)}.${process.pid}.tmp`);
-  const payload = `${JSON.stringify(obj, null, 2)}\n`;
-  fs.writeFileSync(tmp, payload, 'utf8');
+  writeConfigFile(tmp, obj, format);
   fs.renameSync(tmp, filePath);
 }
 
@@ -89,8 +117,7 @@ function atomicWriteJson(filePath, obj) {
  */
 async function runCapabilityCopy(opts) {
   const resolvedPath = resolveCapabilityCopyInputPath(opts.fileOrKey.trim());
-  const raw = fs.readFileSync(resolvedPath, 'utf8');
-  const parsed = JSON.parse(raw);
+  const parsed = readDatasourceConfigFile(resolvedPath);
 
   const to = normalizeCapabilityKey(opts.as, 'Target (--as)');
   const fromRaw = opts.from !== undefined && opts.from !== null ? String(opts.from).trim() : '';
@@ -148,5 +175,6 @@ async function runCapabilityCopy(opts) {
 module.exports = {
   runCapabilityCopy,
   writeBackup,
+  readDatasourceConfigFile,
   atomicWriteJson
 };

package/lib/datasource/capability/run-capability-diff.js

@@ -6,8 +6,8 @@
  * @version 2.0.0
  */
 
-const fs = require('fs');
 const path = require('path');
+const { readDatasourceConfigFile } = require('./run-capability-copy');
 const { resolveValidateInputPath } = require('../validate');
 const { normalizeCapabilityKey } = require('./capability-key');
 const { extractCapabilitySliceForDiff } = require('./capability-diff-slice');
@@ -108,8 +108,8 @@ function resolveProfileKeys(opts) {
 function runCapabilityDiff(opts) {
   const pathA = resolveValidateInputPath(opts.fileA.trim());
   const pathB = resolveValidateInputPath(opts.fileB.trim());
-  const docA = JSON.parse(fs.readFileSync(pathA, 'utf8'));
-  const docB = JSON.parse(fs.readFileSync(pathB, 'utf8'));
+  const docA = readDatasourceConfigFile(pathA);
+  const docB = readDatasourceConfigFile(pathB);
 
   const { capA, capB } = resolveCapabilityKeys(opts);
   const { profA, profB } = resolveProfileKeys(opts);

package/lib/datasource/capability/run-capability-dimension.js

@@ -8,7 +8,6 @@
 
 'use strict';
 
-const fs = require('fs');
 const { resolveControllerUrl } = require('../../utils/controller-url');
 const { normalizeControllerUrl } = require('../../core/config');
 const { getOrRefreshDeviceToken } = require('../../utils/token-manager');
@@ -19,7 +18,7 @@ const {
 } = require('../validate');
 const { applyCapabilityDimension } = require('./dimension-operations');
 const { validateDimensionSemantics } = require('./dimension-validate');
-const { writeBackup, atomicWriteJson } = require('./run-capability-copy');
+const { writeBackup, atomicWriteJson, readDatasourceConfigFile } = require('./run-capability-copy');
 const { tryResolveDatasourceKeyToLocalPath, readJsonFile } = require('../../resolvers/datasource-resolver');
 const { tryFetchDatasourceConfig } = require('../../resolvers/manifest-resolver');
 
@@ -231,8 +230,7 @@ function applyBindingAndValidateSchema({ parsed, opts, semanticWarnings, remoteF
 async function runCapabilityDimension(rawOpts) {
   const opts = normalizeRunOptions(rawOpts);
   const resolvedPath = resolveValidateInputPath(opts.fileOrKey);
-  const raw = fs.readFileSync(resolvedPath, 'utf8');
-  const parsed = JSON.parse(raw);
+  const parsed = readDatasourceConfigFile(resolvedPath);
 
   const systemKeyForAuth = resolveSystemKeyForAuth(parsed);
   const { remoteTargetsByKey, remoteFetchMeta } = await loadRemoteTargetsByKey({

package/lib/datasource/capability/run-capability-edit.js

@@ -6,7 +6,6 @@
  * @version 2.0.0
  */
 
-const fs = require('fs');
 const { execSync } = require('child_process');
 const inquirer = require('inquirer');
 const {
@@ -19,7 +18,8 @@ const {
   resolveSingleOpsKey,
   resolveProfileKeyForLogical
 } = require('./capability-resolve');
-const { writeBackup, atomicWriteJson } = require('./run-capability-copy');
+const { writeBackup, atomicWriteJson, readDatasourceConfigFile } = require('./run-capability-copy');
+const { listCapabilityKeys } = require('./capability-manifest');
 
 /**
  * @typedef {object} RunCapabilityEditOpts
@@ -35,10 +35,7 @@ const { writeBackup, atomicWriteJson } = require('./run-capability-copy');
  * @returns {string[]}
  */
 function collectCapabilityKeys(doc) {
-  const s = new Set();
-  if (Array.isArray(doc.capabilities)) {
-    doc.capabilities.forEach((c) => s.add(String(c)));
-  }
+  const s = new Set(listCapabilityKeys(doc.capabilities));
   if (doc.openapi?.operations) {
     Object.keys(doc.openapi.operations).forEach((k) => s.add(k));
   }
@@ -351,7 +348,7 @@ async function runCapabilityEdit(opts) {
     throw new Error('capability edit requires an interactive terminal (TTY). Use a terminal or SSH with -t.');
   }
   const resolvedPath = resolveValidateInputPath(opts.fileOrKey.trim());
-  const doc = JSON.parse(fs.readFileSync(resolvedPath, 'utf8'));
+  const doc = readDatasourceConfigFile(resolvedPath);
   const { capKey, section, profileKey } = await resolveEditTargets(doc, opts);
   const initial = getEditableJson(doc, capKey, section, profileKey);
   const body = await promptEditorJson(initial);

package/lib/datasource/capability/run-capability-relate.js

@@ -6,14 +6,13 @@
  * @version 2.0.0
  */
 
-const fs = require('fs');
 const {
   resolveValidateInputPath,
   validateDatasourceParsed
 } = require('../validate');
 const { applyCapabilityRelate } = require('./relate-operations');
 const { validateRelateSemantics } = require('./relate-validate');
-const { writeBackup, atomicWriteJson } = require('./run-capability-copy');
+const { writeBackup, atomicWriteJson, readDatasourceConfigFile } = require('./run-capability-copy');
 const { tryResolveDatasourceKeyToLocalPath, readJsonFile } = require('../../resolvers/datasource-resolver');
 const { tryFetchDatasourceConfig } = require('../../resolvers/manifest-resolver');
 
@@ -134,8 +133,7 @@ function applyRelateAndValidateSchema(parsed, opts, semanticWarnings, remoteVali
  */
 async function runCapabilityRelate(opts) {
   const resolvedPath = resolveValidateInputPath(opts.fileOrKey.trim());
-  const raw = fs.readFileSync(resolvedPath, 'utf8');
-  const parsed = JSON.parse(raw);
+  const parsed = readDatasourceConfigFile(resolvedPath);
 
   const targetDocLocal = loadTargetDocLocal(opts.targetDatasource);
   const systemKeyForAuth = resolveSystemKeyForAuth(parsed);

package/lib/datasource/capability/run-capability-remove.js

@@ -6,14 +6,13 @@
  * @version 2.0.0
  */
 
-const fs = require('fs');
 const {
   resolveValidateInputPath,
   validateDatasourceParsed
 } = require('../validate');
 const { normalizeCapabilityKey } = require('./capability-key');
 const { applyCapabilityRemove } = require('./remove-operations');
-const { writeBackup, atomicWriteJson } = require('./run-capability-copy');
+const { writeBackup, atomicWriteJson, readDatasourceConfigFile } = require('./run-capability-copy');
 
 /**
  * @param {{ valid: boolean, errors: string[] }} validation
@@ -67,8 +66,7 @@ function makeRemoveResult(resolvedPath, capability, result, validation, dryRun,
  */
 async function runCapabilityRemove(opts) {
   const resolvedPath = resolveValidateInputPath(opts.fileOrKey.trim());
-  const raw = fs.readFileSync(resolvedPath, 'utf8');
-  const parsed = JSON.parse(raw);
+  const parsed = readDatasourceConfigFile(resolvedPath);
 
   const capability = normalizeCapabilityKey(opts.capability, 'Capability (--capability)');
 

package/lib/datasource/capability/validate-capability-slice.js

@@ -7,6 +7,7 @@
  */
 
 const { normalizeCapabilityKey } = require('./capability-key');
+const { capabilitiesIncludes } = require('./capability-manifest');
 
 /**
  * Lists structural locations where a capability key should appear.
@@ -18,7 +19,7 @@ const { normalizeCapabilityKey } = require('./capability-key');
 function checkCapabilitySlices(parsed, rawKey) {
   const key = normalizeCapabilityKey(rawKey, 'capability');
   const missing = [];
-  if (!Array.isArray(parsed.capabilities) || !parsed.capabilities.includes(key)) {
+  if (!capabilitiesIncludes(parsed.capabilities, key)) {
     missing.push(`capabilities[] (missing "${key}")`);
   }
   if (!parsed.openapi?.operations?.[key]) {

package/lib/datasource/datasource-identifier.js

@@ -38,7 +38,8 @@ function datasourceIdentifierMatchesFile(identifier, fileRef, parsed) {
   if (stem === id) {
     return true;
   }
-  if (`${stem}.json` === id.toLowerCase()) {
+  const lowerId = id.toLowerCase();
+  if (`${stem}.json` === lowerId || `${stem}.yaml` === lowerId || `${stem}.yml` === lowerId) {
     return true;
   }
   return false;

package/lib/datasource/datasource-validate-display.js

@@ -30,7 +30,7 @@ function logHeaderAndIdentity(result, trimmed, showMapping) {
   const { resolvedPath, summary } = result;
   logger.log('');
   logger.log(sectionTitle('Datasource validation'));
-  logger.log(metadata('Offline — JSON schema and integration wiring'));
+  logger.log(metadata('Offline — YAML/JSON schema and integration wiring'));
   logger.log('');
   if (summary) {
     logger.log(`  ${headerKeyValue('Key:', summary.key)}`);

package/lib/datasource/field-reference-validator.js

@@ -10,6 +10,8 @@
  * @version 2.0.0
  */
 
+const { validateOrphanExposedProfiles } = require('./orphan-profiles-validator');
+
 /**
  * Set of attribute names plus root dimension keys valid for field references.
  * Used for primaryKey (schema allows dimension keys or attributes) and other paths (attributes only).
@@ -40,16 +42,34 @@ function checkPrimaryKey(parsed, attributesAndDimensions, errors) {
   });
 }
 
+/** @returns {Set<string>} */
+function profileReferenceSet(parsed) {
+  if (parsed?.entityType === 'serviceContract') {
+    const schema = parsed?.exposed?.schema;
+    if (schema && typeof schema === 'object' && !Array.isArray(schema)) {
+      return new Set(
+        Object.keys(schema).filter(key => typeof key === 'string' && key !== '')
+      );
+    }
+  }
+  return new Set(Object.keys(parsed?.fieldMappings?.attributes ?? {}));
+}
+
 /** @param {string[]} errors */
-function checkExposedProfiles(parsed, attrSet, errors) {
+function checkExposedProfiles(parsed, _attrSet, errors) {
   const profiles = parsed?.exposed?.profiles;
   if (!profiles || typeof profiles !== 'object' || Array.isArray(profiles)) return;
+  const profileRefSet = profileReferenceSet(parsed);
+  const referenceLabel =
+    parsed?.entityType === 'serviceContract'
+      ? 'exposed.schema'
+      : 'fieldMappings.attributes';
   Object.entries(profiles).forEach(([profileName, fields]) => {
     if (!Array.isArray(fields)) return;
     fields.forEach((field, idx) => {
-      if (typeof field === 'string' && !attrSet.has(field)) {
+      if (typeof field === 'string' && !profileRefSet.has(field)) {
         errors.push(
-          `exposed.profiles.${profileName}[${idx}]: field '${field}' does not exist in fieldMappings.attributes. Add the attribute or remove the reference.`
+          `exposed.profiles.${profileName}[${idx}]: field '${field}' does not exist in ${referenceLabel}. Add the attribute or remove the reference.`
         );
       }
     });
@@ -121,6 +141,7 @@ function validateFieldReferences(parsed) {
 
   checkPrimaryKey(parsed, attributesAndDimensions, errors);
   checkExposedProfiles(parsed, attrSet, errors);
+  errors.push(...validateOrphanExposedProfiles(parsed));
   if (normalizedAttributes.length === 0) return errors;
 
   checkIndexingAndValidation(parsed, normalizedAttributes, errors);