@aifabrix/builder 2.45.5 → 2.47.0

package/lib/commands/repair-auth-apply.js

@@ -0,0 +1,153 @@
+/**
+ * Repair --auth: canonical authentication blocks and bearerToken preset.
+ *
+ * Applies canonical authentication blocks for repair --auth.
+ *
+ * @fileoverview Repair authentication method application
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const {
+  buildAuthenticationFromMethod,
+  getAuthCredentialTemplate,
+  migrateAuthenticationToNestedSchema
+} = require('../utils/authentication-shape');
+
+/** Repair CLI --auth values (normalized lowercase). */
+const ALLOWED_REPAIR_AUTH = [
+  'oauth2',
+  'aad',
+  'apikey',
+  'bearertoken',
+  'bearerkey',
+  'basic',
+  'queryparam',
+  'oidc',
+  'hmac',
+  'none'
+];
+
+const PRESERVED_VARIABLE_KEYS = ['baseUrl', 'testEndpoint'];
+
+/**
+ * @param {string} authOption - Raw --auth value
+ * @returns {string} Normalized lowercase auth option
+ */
+function normalizeRepairAuthOption(authOption) {
+  return String(authOption || '').trim().toLowerCase();
+}
+
+/**
+ * @param {string} authOption - Normalized --auth value
+ * @returns {boolean}
+ */
+function isAllowedRepairAuth(authOption) {
+  return ALLOWED_REPAIR_AUTH.includes(normalizeRepairAuthOption(authOption));
+}
+
+/**
+ * Builds authentication block for repair --auth.
+ * @param {string} systemKey - System key
+ * @param {string} authOption - Normalized repair auth (e.g. bearertoken, apikey)
+ * @returns {{ method: string, variables: Object, security: Object }}
+ */
+function buildAuthenticationForRepair(systemKey, authOption) {
+  const normalized = normalizeRepairAuthOption(authOption);
+  const schemaMethod =
+    normalized === 'queryparam'
+      ? 'queryParam'
+      : normalized === 'bearertoken' || normalized === 'bearerkey'
+        ? 'bearerToken'
+        : normalized;
+  return buildAuthenticationFromMethod(systemKey, schemaMethod);
+}
+
+/**
+ * Merges preserved connectivity fields from existing auth into template variables.
+ * @param {Object} mergedVariables - Target variables object (mutated)
+ * @param {Object} existingVars - Prior authentication.variables
+ */
+function mergePreservedAuthVariables(mergedVariables, existingVars) {
+  if (!existingVars || typeof existingVars !== 'object') return;
+  for (const key of PRESERVED_VARIABLE_KEYS) {
+    if (existingVars[key] !== undefined && existingVars[key] !== null) {
+      mergedVariables[key] = existingVars[key];
+    }
+  }
+}
+
+/**
+ * Human-readable label for repair change log.
+ * @param {string} authOption - Normalized repair auth
+ * @returns {string}
+ */
+function repairAuthChangeLabel(authOption) {
+  const normalized = normalizeRepairAuthOption(authOption);
+  if (normalized === 'bearertoken' || normalized === 'bearerkey') return 'bearerToken';
+  return normalized;
+}
+
+const MISSING_TEST_ENDPOINT_WARNING =
+  'authentication.variables.testEndpoint is missing for apikey/bearerToken auth — add a GET URL for credential/E2E tests (e.g. /crm/v3/objects/contacts?limit=1, or a path resolved against baseUrl).';
+
+/**
+ * Warn when apikey auth (including bearerToken preset) has no testEndpoint.
+ * @param {Object} authentication - authentication block on system file
+ * @param {string[]} warnings - Mutable warnings list
+ */
+function appendTestEndpointWarningIfMissing(authentication, warnings) {
+  const credential = getAuthCredentialTemplate(authentication);
+  const method = String(credential?.method || authentication?.method || '').toLowerCase();
+  if (method !== 'apikey' && method !== 'bearertoken') return;
+  const testEndpoint = String(credential?.variables?.testEndpoint || authentication?.variables?.testEndpoint || '').trim();
+  if (testEndpoint) return;
+  if (warnings.includes(MISSING_TEST_ENDPOINT_WARNING)) return;
+  warnings.push(MISSING_TEST_ENDPOINT_WARNING);
+}
+
+/**
+ * Audit system authentication after repair (with or without --auth).
+ * @param {Object} systemParsed - Parsed system config
+ * @param {string[]} warnings - Mutable warnings list
+ */
+function auditRepairAuthenticationWarnings(systemParsed, warnings) {
+  const authentication = systemParsed?.authentication || systemParsed?.auth;
+  if (!authentication || typeof authentication !== 'object') return;
+  appendTestEndpointWarningIfMissing(authentication, warnings);
+}
+
+/**
+ * Ensures system file authentication matches nested schema (authType + credential).
+ * @param {Object} systemParsed - Parsed system config (mutated)
+ * @param {string} systemKey
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function normalizeAuthenticationSchemaShape(systemParsed, systemKey, changes) {
+  const current = systemParsed.authentication || systemParsed.auth;
+  const { authentication, changed } = migrateAuthenticationToNestedSchema(current, systemKey);
+  if (!changed) {
+    return false;
+  }
+  systemParsed.authentication = authentication;
+  delete systemParsed.auth;
+  changes.push('Normalized authentication to authType + credential (schema 2.4.x)');
+  return true;
+}
+
+module.exports = {
+  ALLOWED_REPAIR_AUTH,
+  MISSING_TEST_ENDPOINT_WARNING,
+  normalizeRepairAuthOption,
+  isAllowedRepairAuth,
+  buildAuthenticationForRepair,
+  mergePreservedAuthVariables,
+  repairAuthChangeLabel,
+  appendTestEndpointWarningIfMissing,
+  auditRepairAuthenticationWarnings,
+  normalizeAuthenticationSchemaShape,
+  getAuthCredentialTemplate
+};

package/lib/commands/repair-auth-config.js

@@ -8,17 +8,7 @@
 'use strict';
 
 const { systemKeyToKvPrefix, securityKeyToVar, kvEnvKeyToPath } = require('../utils/credential-secrets-env');
-
-/**
- * Returns true if a kv value looks like legacy format (KeyVault suffix or no path segments).
- * @param {string} val - Value from authentication.security or configuration
- * @returns {boolean}
- */
-function isLegacyKvValue(val) {
-  if (typeof val !== 'string' || !val.trim().toLowerCase().startsWith('kv://')) return false;
-  const after = val.trim().slice(5); // after 'kv://'
-  return after.includes('KeyVault') || !after.includes('/');
-}
+const { isLegacyKvValue } = require('../utils/platform-kv-ref');
 
 /**
  * Normalizes authentication.security keyvault entries to path-style kv:// values (kv://systemKey/variable).
@@ -87,7 +77,9 @@ function normalizeConfigurationSection(config, prefix, systemKey, changes) {
 function normalizeSystemFileAuthAndConfig(systemParsed, systemKey, changes) {
   const prefix = systemKeyToKvPrefix(systemKey);
   if (!prefix) return false;
-  const security = systemParsed.authentication?.security;
+  const { getAuthCredentialTemplate } = require('../utils/authentication-shape');
+  const credential = getAuthCredentialTemplate(systemParsed.authentication);
+  const security = credential?.security ?? systemParsed.authentication?.security;
   let updated = (security && typeof security === 'object' && normalizeSecuritySection(security, prefix, systemKey, changes));
   const config = systemParsed.configuration;
   if (Array.isArray(config)) {
@@ -96,4 +88,7 @@ function normalizeSystemFileAuthAndConfig(systemParsed, systemKey, changes) {
   return updated;
 }
 
-module.exports = { normalizeSystemFileAuthAndConfig, isLegacyKvValue };
+module.exports = {
+  normalizeSystemFileAuthAndConfig,
+  isLegacyKvValue
+};

package/lib/commands/repair-changed-files.js

@@ -0,0 +1,41 @@
+/**
+ * Track integration files touched during repair for CLI summary output.
+ *
+ * @fileoverview Repair changed-file tracking
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+
+/**
+ * Ensures backup/repair context has changed-file buckets.
+ * @param {Object} ctx - Repair backup context
+ * @returns {{ changedFiles: string[], wouldChangeFiles: string[] }}
+ */
+function ensureChangedFileBuckets(ctx) {
+  if (!ctx) return { changedFiles: [], wouldChangeFiles: [] };
+  if (!Array.isArray(ctx.changedFiles)) ctx.changedFiles = [];
+  if (!Array.isArray(ctx.wouldChangeFiles)) ctx.wouldChangeFiles = [];
+  return { changedFiles: ctx.changedFiles, wouldChangeFiles: ctx.wouldChangeFiles };
+}
+
+/**
+ * Records a file path that repair wrote or would write (dry-run).
+ * @param {string} filePath - Path to file
+ * @param {Object} ctx - Repair context with dryRun, changedFiles, wouldChangeFiles
+ */
+function trackRepairWrite(filePath, ctx) {
+  if (!filePath || !ctx) return;
+  const abs = path.resolve(filePath);
+  const { changedFiles, wouldChangeFiles } = ensureChangedFileBuckets(ctx);
+  const bucket = ctx.dryRun ? wouldChangeFiles : changedFiles;
+  if (!bucket.includes(abs)) bucket.push(abs);
+}
+
+module.exports = {
+  ensureChangedFileBuckets,
+  trackRepairWrite
+};

package/lib/commands/repair-datasource-com-v2.js

@@ -0,0 +1,15 @@
+/**
+ * COM v2 datasource manifest repair (capabilities objects, strip context).
+ *
+ * @fileoverview repair-datasource-com-v2
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { repairComV2Manifest } = require('../datasource/capability/capability-manifest');
+
+module.exports = {
+  repairComV2Manifest
+};

package/lib/commands/repair-datasource-keys.js

@@ -16,6 +16,7 @@ const path = require('path');
 const fs = require('fs');
 const { loadConfigFile, writeConfigFile } = require('../utils/config-format');
 const { backupIntegrationFile } = require('../utils/integration-file-backup');
+const { trackRepairWrite } = require('./repair-changed-files');
 
 /**
  * Returns suffix from a canonical-format filename: <systemKey>-datasource-<suffix>.<ext>.
@@ -174,8 +175,9 @@ function normalizeDatasourceKeysAndFilenames(appPath, datasourceFiles, systemKey
 
     if (parsed.key !== canonicalKey) {
       parsed.key = canonicalKey;
+      const fullPath = path.join(appPath, fileName);
+      trackRepairWrite(fullPath, backupCtx);
       if (!dryRun) {
-        const fullPath = path.join(appPath, fileName);
         backupIntegrationFile(fullPath, backupCtx);
         writeConfigFile(fullPath, parsed);
       }
@@ -185,6 +187,7 @@ function normalizeDatasourceKeysAndFilenames(appPath, datasourceFiles, systemKey
     if (fileName !== canonicalFileName) {
       const oldPath = path.join(appPath, fileName);
       const newPath = path.join(appPath, canonicalFileName);
+      trackRepairWrite(newPath, backupCtx);
       if (!dryRun && fs.existsSync(oldPath) && !fs.existsSync(newPath)) {
         backupIntegrationFile(oldPath, backupCtx);
         fs.renameSync(oldPath, newPath);

package/lib/commands/repair-datasource-run.js

@@ -0,0 +1,59 @@
+/**
+ * Batch datasource file repair during external integration repair.
+ *
+ * @fileoverview Run repairDatasourceFile across integration datasource files
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { loadConfigFile, writeConfigFile } = require('../utils/config-format');
+const { backupIntegrationFile } = require('../utils/integration-file-backup');
+const { trackRepairWrite } = require('./repair-changed-files');
+const { repairDatasourceFile } = require('./repair-datasource');
+
+/**
+ * @param {string} appPath
+ * @param {string[]} datasourceFiles
+ * @param {Object} options
+ * @param {boolean} dryRun
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function runDatasourceRepairs(appPath, datasourceFiles, options, dryRun, changes) {
+  if (!datasourceFiles || datasourceFiles.length === 0) return false;
+  let updated = false;
+  for (const fileName of datasourceFiles) {
+    const filePath = path.join(appPath, fileName);
+    if (!fs.existsSync(filePath)) continue;
+    try {
+      const parsed = loadConfigFile(filePath);
+      const { updated: fileUpdated, changes: fileChanges } = repairDatasourceFile(parsed, {
+        expose: options.expose,
+        sync: options.sync,
+        test: options.test
+      });
+      if (fileUpdated) {
+        updated = true;
+        fileChanges.forEach(c => changes.push(`${fileName}: ${c}`));
+        if (!dryRun) {
+          backupIntegrationFile(filePath, options.backupCtx);
+          writeConfigFile(filePath, parsed);
+        }
+        trackRepairWrite(filePath, options.backupCtx);
+      }
+    } catch (err) {
+      logger.log(chalk.yellow(`⚠ Could not repair datasource ${fileName}: ${err.message}`));
+    }
+  }
+  return updated;
+}
+
+module.exports = {
+  runDatasourceRepairs
+};

package/lib/commands/repair-datasource-service-contract.js

@@ -0,0 +1,206 @@
+/**
+ * serviceContract repair helpers — migrate deprecated none+llm manifests (439.1).
+ *
+ * @fileoverview repair-datasource-service-contract
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const LLM_CANONICAL_METADATA_SCHEMA = {
+  type: 'object',
+  properties: {
+    successContent: { type: 'string', nullable: true },
+    successEmbedding: {
+      type: 'array',
+      items: { type: 'number' },
+      nullable: true
+    },
+    successRole: { type: 'string', nullable: true },
+    successModel: { type: 'string', nullable: true },
+    successFinishReason: { type: 'string', nullable: true },
+    errorCode: { type: 'string', nullable: true },
+    errorMessage: { type: 'string', nullable: true },
+    errorType: { type: 'string', nullable: true },
+    usagePromptTokens: { type: 'integer', nullable: true },
+    usageCompletionTokens: { type: 'integer', nullable: true },
+    usageTotalTokens: { type: 'integer', nullable: true },
+    metadataProvider: { type: 'string', nullable: true },
+    metadataOperation: { type: 'string', nullable: true }
+  }
+};
+
+const LLM_CANONICAL_EXPOSED_SCHEMA = {
+  success: {
+    content: 'metadata.successContent',
+    embedding: 'metadata.successEmbedding',
+    role: 'metadata.successRole',
+    model: 'metadata.successModel',
+    finishReason: 'metadata.successFinishReason'
+  },
+  error: {
+    code: 'metadata.errorCode',
+    message: 'metadata.errorMessage',
+    type: 'metadata.errorType'
+  },
+  usage: {
+    promptTokens: 'metadata.usagePromptTokens',
+    completionTokens: 'metadata.usageCompletionTokens',
+    totalTokens: 'metadata.usageTotalTokens'
+  },
+  metadata: {
+    provider: 'metadata.metadataProvider',
+    operation: 'metadata.metadataOperation'
+  }
+};
+
+const LLM_STUB_FIELD_MAPPINGS = {
+  successContent: { expression: '{{raw}}' },
+  metadataProvider: { expression: '{{inline.metadataProvider}}' },
+  metadataOperation: { expression: '{{inline.metadataOperation}}' }
+};
+
+/**
+ * @param {Object} parsed - Parsed datasource manifest
+ * @returns {boolean}
+ */
+function isDeprecatedNoneLlmManifest(parsed) {
+  return parsed?.entityType === 'none' && parsed?.resourceType === 'llm';
+}
+
+/**
+ * @param {Object} parsed
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function stripStorageKeysForServiceContract(parsed, changes) {
+  let updated = false;
+  for (const key of ['primaryKey', 'labelKey', 'sync']) {
+    if (parsed[key] !== undefined) {
+      delete parsed[key];
+      changes.push(`Removed ${key} (not allowed on serviceContract)`);
+      updated = true;
+    }
+  }
+  return updated;
+}
+
+/**
+ * @param {Object} parsed
+ * @param {string} systemKey
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function ensureLlmCipMapSteps(parsed, systemKey, changes) {
+  const operations = parsed?.execution?.cip?.operations;
+  if (!operations || typeof operations !== 'object') return false;
+  let updated = false;
+  for (const opKey of ['call', 'embed']) {
+    const op = operations[opKey];
+    if (!op || !Array.isArray(op.steps)) continue;
+    if (op.steps.some((step) => step && step.map)) continue;
+    const fetchIdx = op.steps.findIndex((step) => step && step.fetch);
+    if (fetchIdx < 0) continue;
+    const mapStep = {
+      map: {
+        useFieldMappings: true,
+        inputPath: '$',
+        inline: {
+          metadataProvider: systemKey || parsed.systemKey || 'provider',
+          metadataOperation: opKey
+        }
+      }
+    };
+    op.steps.splice(fetchIdx + 1, 0, mapStep);
+    if (!op.steps.some((step) => step && step.output)) {
+      op.steps.push({ output: { mode: 'records' } });
+    }
+    changes.push(`Inserted map+output steps for CIP operation "${opKey}"`);
+    updated = true;
+  }
+  return updated;
+}
+
+/**
+ * @param {Object} parsed
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function stripDeprecatedServiceCategory(parsed, changes) {
+  if (parsed?.serviceCategory === undefined) return false;
+  delete parsed.serviceCategory;
+  changes.push('Removed deprecated serviceCategory (use resourceType for classification)');
+  return true;
+}
+
+/**
+ * @param {*} value
+ * @returns {*}
+ */
+function deepClone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+/**
+ * @param {Object} parsed
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function applyCanonicalLlmSchemaStubs(parsed, changes) {
+  parsed.entityType = 'serviceContract';
+  changes.push('Migrated entityType none → serviceContract');
+
+  parsed.metadataSchema = deepClone(LLM_CANONICAL_METADATA_SCHEMA);
+  changes.push('Set canonical LLM metadataSchema stub');
+
+  if (!parsed.exposed) parsed.exposed = {};
+  parsed.exposed.schema = deepClone(LLM_CANONICAL_EXPOSED_SCHEMA);
+  if (parsed.exposed.attributes !== undefined) {
+    delete parsed.exposed.attributes;
+  }
+  changes.push('Set canonical LLM exposed.schema envelope');
+  return true;
+}
+
+/**
+ * @param {Object} parsed
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function applyStubFieldMappingsIfMissing(parsed, changes) {
+  const attrs = parsed.fieldMappings?.attributes;
+  if (attrs && typeof attrs === 'object' && Object.keys(attrs).length > 0) {
+    return false;
+  }
+  if (!parsed.fieldMappings) parsed.fieldMappings = {};
+  parsed.fieldMappings.attributes = deepClone(LLM_STUB_FIELD_MAPPINGS);
+  changes.push(
+    'Added stub fieldMappings.attributes — customize provider raw.* expressions'
+  );
+  return true;
+}
+
+/**
+ * Migrate deprecated none+llm manifest to serviceContract canonical stub.
+ *
+ * @param {Object} parsed - Parsed datasource (mutated)
+ * @param {string[]} changes - Change log
+ * @returns {boolean}
+ */
+function repairNoneLlmToServiceContract(parsed, changes) {
+  if (!isDeprecatedNoneLlmManifest(parsed)) return false;
+  let updated = applyCanonicalLlmSchemaStubs(parsed, changes);
+  updated = applyStubFieldMappingsIfMissing(parsed, changes) || updated;
+  updated = stripStorageKeysForServiceContract(parsed, changes) || updated;
+  updated = ensureLlmCipMapSteps(parsed, parsed.systemKey, changes) || updated;
+  return updated;
+}
+
+module.exports = {
+  LLM_CANONICAL_METADATA_SCHEMA,
+  LLM_CANONICAL_EXPOSED_SCHEMA,
+  isDeprecatedNoneLlmManifest,
+  stripDeprecatedServiceCategory,
+  repairNoneLlmToServiceContract
+};